31 次重大版本更新

34.0.0 2024 年 6 月 24 日
33.0.0 2024 年 5 月 23 日
32.0.0 2024 年 5 月 1 日
31.0.0 2024 年 4 月 9 日
0.0.0 2022 年 11 月 21 日

#481 in 神奇豆子


用于 模块示例

MIT-0 许可证

2.5MB
42K SLoC

基本示例模块

示例:一个简单的 FRAME 模块示例,展示了大多数 FRAME 运行时中常见的概念、API 和结构。

运行 cargo doc --package pallet-example-basic --open 来查看此模块的文档。

此模块作为示例,不建议用于生产环境。

文档指南

  • 文档注释(即 /// 注释)——应伴随 pallet 函数,并限制在 pallet 接口中,而不是 pallet 实现的内部。仅包括状态输入、输出和简短描述,提及是否需要 root 权限,但不重复源代码细节。每个文档注释的首字母大写,并以句号结束。见 源代码注释的通用示例
  • 自文档代码——尝试重构代码以实现自文档化。
  • 代码注释——用简短的解释补充复杂代码,而不是每行代码。
  • 标识符——用反引号包围(例如 INHERENT_IDENTIFIERInherentTypeu64
  • 使用场景——应该是简单的 doctests。编译器应确保它们保持有效。
  • 扩展教程——应移至外部文件并引用。
  • 必须包含——包含所有指定 必须 的部分/子部分。
  • 可选包含——可选包含指定 可以 的部分/子部分。

文档模板

将此模板从 frame/examples/basic/src/lib.rs 复制并粘贴到您的自定义 pallet 的文件 frame/<INSERT_CUSTOM_PALLET_NAME>/src/lib.rs 中,并完成它。

// Add heading with custom pallet name

# <INSERT_CUSTOM_PALLET_NAME> Pallet

// Add simple description

// Include the following links that shows what trait needs to be implemented to use the pallet // and the supported dispatchables that are documented in the Call enum.

## Overview

// Short description of pallet's purpose. // Links to Traits that should be implemented. // What this pallet is for. // What functionality the pallet provides. // When to use the pallet (use case examples). // How it is used. // Inputs it uses and the source of each input. // Outputs it produces.

## Terminology

// Add terminology used in the custom pallet. Include concepts, storage items, or actions that you think // deserve to be noted to give context to the rest of the documentation or pallet usage. The author needs to // use some judgment about what is included. We don't want a list of every storage item nor types - the user // can go to the code for that. For example, "transfer fee" is obvious and should not be included, but // "free balance" and "reserved balance" should be noted to give context to the pallet. // Please do not link to outside resources. The reference docs should be the ultimate source of truth.

## Goals

// Add goals that the custom pallet is designed to achieve.

### Scenarios

#### <INSERT_SCENARIO_NAME>

// Describe requirements prior to interacting with the custom pallet. // Describe the process of interacting with the custom pallet for this scenario and public API functions used.

## Interface

### Supported Origins

// What origins are used and supported in this pallet (root, signed, none) // i.e. root when `ensure_root` used // i.e. none when `ensure_none` used // i.e. signed when `ensure_signed` used

`inherent` <INSERT_DESCRIPTION>

### Types

// Type aliases. Include any associated types and where the user would typically define them.

`ExampleType` <INSERT_DESCRIPTION>

// Reference documentation of aspects such as storageItems and dispatchable functions should only be // included in the https://docs.rs Rustdocs for Substrate and not repeated in the README file.

### Dispatchable Functions

// A brief description of dispatchable functions and a link to the rustdoc with their actual documentation.

// MUST have link to Call enum // MUST have origin information included in function doc // CAN have more info up to the user

### Public Functions

// A link to the rustdoc and any notes about usage in the pallet, not for specific functions. // For example, in the Balances Pallet: "Note that when using the publicly exposed functions, // you (the runtime developer) are responsible for implementing any necessary checks // (e.g. that the sender is the signer) before calling a function that will affect storage."

// It is up to the writer of the respective pallet (with respect to how much information to provide).

#### Public Inspection functions - Immutable (getters)

// Insert a subheading for each getter function signature

##### `example_getter_name()`

// What it returns // Why, when, and how often to call it // When it could panic or error // When safety issues to consider

#### Public Mutable functions (changing state)

// Insert a subheading for each setter function signature

##### `example_setter_name(origin, parameter_name: T::ExampleType)`

// What state it changes // Why, when, and how often to call it // When it could panic or error // When safety issues to consider // What parameter values are valid and why

### Storage Items

// Explain any storage items included in this pallet

### Digest Items

// Explain any digest items included in this pallet

### Inherent Data

// Explain what inherent data (if any) is defined in the pallet and any other related types

### Events:

// Insert events for this pallet if any

### Errors:

// Explain what generates errors

## Usage

// Insert 2-3 examples of usage and code snippets that show how to // use <INSERT_CUSTOM_PALLET_NAME> Pallet in a custom pallet.

### Prerequisites

// Show how to include necessary imports for <INSERT_CUSTOM_PALLET_NAME> and derive // your pallet configuration trait with the INSERT_CUSTOM_PALLET_NAME trait.

```rust use <INSERT_CUSTOM_PALLET_NAME>;

pub trait Config: <INSERT_CUSTOM_PALLET_NAME>::Config { } ```

### Simple Code Snippet

// Show a simple example (e.g. how to query a public getter function of <INSERT_CUSTOM_PALLET_NAME>)

### Example from FRAME

// Show a usage example in an actual runtime

// See: // - Substrate TCR https://github.com/parity-samples/substrate-tcr // - Substrate Kitties https://shawntabrizi.github.io/substrate-collectables-workshop/#/

## Genesis Config

## Dependencies

// Dependencies on other FRAME pallets and the genesis config should be mentioned, // but not the Rust Standard Library. // Genesis configuration modifications that may be made to incorporate this pallet // Interaction with other pallets

## Related Pallets

// Interaction with other pallets in the form of a bullet point list

## References

// Links to reference material, if applicable. For example, Phragmen, W3F research, etc. // that the implementation is based on.

许可:MIT-0

依赖项

~17–32MB
~538K SLoC