pezkuwichain/pezkuwi-subxt
1
0
Fork 0
mirror of https://github.com/pezkuwichain/pezkuwi-subxt.git synced 2026-04-26 01:47:55 +00:00
Code Issues Packages Projects Releases Wiki Activity

[improve docs]: Timestamp pallet (#1435)

Browse Source 
This PR improves the docs for the Timestamp pallet by following our
[Documentation
Guidelines](https://github.com/paritytech/polkadot-sdk/blob/master/docs/DOCUMENTATION_GUIDELINE.md)
more closely.

---------

Co-authored-by: Juan <juangirini@gmail.com>
Co-authored-by: Francisco Aguirre <franciscoaguirreperez@gmail.com>
This commit is contained in:
Sacha Lansky
2023-09-18 11:09:17 +02:00
committed by GitHub
parent 1d5a9d25e2
commit f6072e8be3
6 changed files with 127 additions and 77 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/DOCUMENTATION_GUIDELINE.md
+16 -17
View File
@@ -123,9 +123,9 @@ explicitly depend on them, you have likely not designed it properly.
#### Proc-Macros
Note that there are special considerations when documenting proc macros. Doc links will appear to function _within_ your
Note that there are special considerations when documenting proc macros. Doc links will appear to function *within* your
proc macro crate, but often will no longer function when these proc macros are re-exported elsewhere in your project.
The exception is doc links to _other proc macros_ which will function just fine if they are also being re-exported. It
The exception is doc links to *other proc macros* which will function just fine if they are also being re-exported. It
is also often necessary to disambiguate between a proc macro and a function of the same name, which can be done using
the `macro@my_macro_name` syntax in your link. Read more about how to correctly use links in your rust-docs
[here](https://doc.rust-lang.org/rustdoc/write-documentation/linking-to-items-by-name.html#valid-links) and
@@ -189,6 +189,7 @@ fn multiply_by_2(x: u32) -> u32 { .. }
// More efficiency can be achieved if we improve this via such and such.
fn multiply_by_2(x: u32) -> u32 { .. }
```
They are both roughly conveying the same set of facts, but one is easier to follow because it was formatted cleanly.
Especially for traits and types that you can foresee will be seen and used a lot, try and write a well formatted
version.
@@ -203,7 +204,6 @@ properly do this.
---
## Pallet Crates
The guidelines so far have been general in nature, and are applicable to crates that are pallets and crates that're not
@@ -223,6 +223,14 @@ For the top-level pallet docs, consider the following template:
//!
//! <single-liner about the pallet>.
//!
//! ## Pallet API
//!
//! <Reminder: inside the [`pallet`] module, a template that leads the reader to the relevant items is auto-generated. There is no need to repeat
//! things like "See Config trait for ...", which are generated inside [`pallet`] here anyways. You can use the line below as-is:>
//!
//! See the [`pallet`] module for more information about the interfaces this pallet exposes, including its
//! configuration trait, dispatchables, storage items, events and errors.
//!
//! ## Overview
//!
//! <should be high-level details that are relevant to the most broad audience>
@@ -233,20 +241,12 @@ For the top-level pallet docs, consider the following template:
//!
//! ### Example
//!
//! <Your pallet must have a few tests that cover important user journeys. Use https://crates.io/crates/docify to reuse
//! these as examples>.
//! <Your pallet must have a few tests that cover important user journeys. Use https://crates.io/crates/docify to
//! reuse these as examples.>
//!
//! ## Pallet API
//!
//! <Reminder: inside the [`pallet`] module, a template that leads the reader to the relevant items is auto-generated.
//! There is no need to repeat things like "See Config trait for ...", which are generated inside [`pallet`] here anyways.
//! You can use the below line as-is:>
//!
//! See the [`pallet`] module for more information about the interfaces this pallet exposes, including its configuration
//! trait, dispatchables, storage items, events and errors.
//!
//! <The audience of this is those who want to know how this pallet works, to the extent of being able to build something
//! on top of it, like a DApp or another pallet>
//! <The audience of this is those who want to know how this pallet works, to the extent of being able to build
//! something on top of it, like a DApp or another pallet. In some cases, you might want to add an example of how to
//! use this pallet in other pallets.>
//!
//! This section can most often be left as-is.
//!
@@ -272,7 +272,6 @@ For the top-level pallet docs, consider the following template:
//! up>
```
This template's details (heading 3s and beyond) are left flexible, and at the discretion of the developer to make the
best final choice about. For example, you might want to include `### Terminology` or not. Moreover, you might find it
more useful to include it in `## Overview`.