Skip to content
This repository was archived by the owner on Nov 15, 2023. It is now read-only.

improve docs #2068

Merged
gavofyork merged 7 commits into from
Mar 26, 2019
Merged

improve docs #2068

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
b53b64d
improve decl_storage instance doc
gui1117 Mar 21, 2019
56e966f
use decl_event doc accordignly
gui1117 Mar 21, 2019
e3ba1bf
automate doc and while allow to extend it on event
gui1117 Mar 22, 2019
313d06a
some missed ones
gui1117 Mar 22, 2019
1f21055
Update srml/example/src/lib.rs
joepetrowski Mar 25, 2019
df3b483
Update srml/support/procedural/src/storage/transformation.rs
gui1117 Mar 25, 2019
a4b6ab6
Merge remote-tracking branch 'origin/master' into gui-improve-docs
gui1117 Mar 25, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 1 addition & 3 deletions srml/assets/src/lib.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -82,10 +82,8 @@ decl_module! {
}
}

/// An event in this module. Events are simple means of reporting specific conditions and
/// circumstances that have happened that users, Dapps and/or chain explorers would find
/// interesting and otherwise difficult to detect.
decl_event!(
/// An event in this module.
Copy link
Contributor

@joepetrowski joepetrowski Mar 21, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let's agree on one correct comment to go here, before the pub enum Event and use it for each module. I think "/// Events for this module." would be ok.

Copy link
Contributor Author

@gui1117 gui1117 Mar 21, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ok,
(as a note: if no module need to have a more explicit description, we can make it generated by the macro and remove the ability to customize)

Copy link
Contributor

@joepetrowski joepetrowski Mar 21, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That is probably better, because the notion of "events" could change, and we don't want to update the same comment in the entire SRML. There is documentation (at least in progress) on the Event type. Perhaps it makes sense to have a more thorough comment in srml/example/src/lib.rs and node-template/runtime/src/template.rs. Everything else should be consistent unless there is a unique feature to a module.

Copy link
Member

@shawntabrizi shawntabrizi Mar 22, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

+1 for macro generation

Copy link
Contributor Author

@gui1117 gui1117 Mar 22, 2019 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

macro generation now as such:

/// Events for this module.
///
/// (other doc of user if some)

pub enum Event<T> where <T as system::Trait>::AccountId, <T as Trait>::Balance {
/// Some assets were issued.
Issued(AssetId, AccountId, Balance),
Expand Down
2 changes: 1 addition & 1 deletion srml/council/src/motions.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -47,8 +47,8 @@ pub enum Origin {
Members(u32),
}

/// Event for this module.
decl_event!(
/// Event for this module.
pub enum Event<T> where <T as system::Trait>::Hash, <T as system::Trait>::AccountId {
/// A motion (given hash) has been proposed (by given account) with a threshold (given u32).
Proposed(AccountId, ProposalIndex, Hash, u32),
Expand Down
2 changes: 1 addition & 1 deletion srml/council/src/voting.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -125,8 +125,8 @@ decl_storage! {
}
}

/// An event in this module.
decl_event!(
/// An event in this module.
pub enum Event<T> where <T as system::Trait>::Hash {
/// A voting tally has happened for a referendum cancellation vote.
/// Last three are yes, no, abstain counts.
Expand Down
6 changes: 3 additions & 3 deletions srml/example/src/lib.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -72,10 +72,10 @@ decl_storage! {
}
}

/// An event in this module. Events are simple means of reporting specific conditions and
/// circumstances that have happened that users, Dapps and/or chain explorers would find
/// interesting and otherwise difficult to detect.
decl_event!(
/// An event in this module. Events are simple means of reporting specific conditions and
/// circumstances that have happened that users, Dapps and/or chain explorers would find
/// interesting and otherwise difficult to detect.
pub enum Event<T> where B = <T as balances::Trait>::Balance {
// Just a normal `enum`, here's a dummy event to ensure it compiles.
/// Dummy event, just here so there's a generic type that's used.
Expand Down
2 changes: 1 addition & 1 deletion srml/grandpa/src/lib.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -176,8 +176,8 @@ impl<N: Decode, SessionKey: Decode> Decode for StoredPendingChange<N, SessionKey
}
}

/// GRANDPA events.
decl_event!(
/// GRANDPA events.
pub enum Event<T> where <T as Trait>::SessionKey {
/// New authority set has been applied.
NewAuthorities(Vec<(SessionKey, u64)>),
Expand Down
2 changes: 1 addition & 1 deletion srml/session/src/lib.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -84,8 +84,8 @@ decl_module! {
}
}

/// An event in this module.
decl_event!(
/// An event in this module.
pub enum Event<T> where <T as system::Trait>::BlockNumber {
/// New session has happened. Note that the argument is the session index, not the block
/// number as the type might suggest.
Expand Down
2 changes: 1 addition & 1 deletion srml/staking/src/lib.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -488,8 +488,8 @@ decl_module! {
}
}

/// An event in this module.
decl_event!(
/// An event in this module.
pub enum Event<T> where Balance = BalanceOf<T>, <T as system::Trait>::AccountId {
/// All validators have been rewarded by the given balance.
Reward(Balance),
Expand Down
2 changes: 1 addition & 1 deletion srml/sudo/src/lib.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -58,8 +58,8 @@ decl_module! {
}
}

/// An event in this module.
decl_event!(
/// An event in this module.
pub enum Event<T> where AccountId = <T as system::Trait>::AccountId {
/// A sudo just took place.
Sudid(bool),
Expand Down
8 changes: 5 additions & 3 deletions srml/support/procedural/src/storage/transformation.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -500,6 +500,7 @@ fn decl_storage_items(
}

impls.extend(quote! {
/// Instance trait implemented by all usable instance of the module.
pub trait #instantiable: 'static {
#const_impls
}
Expand All @@ -510,12 +511,12 @@ fn decl_storage_items(
.map(|i| {
let name = format!("Instance{}", i);
let ident = syn::Ident::new(&name, proc_macro2::Span::call_site());
(name, ident)
(name, ident, quote! {#[doc=r"Module instance"]})
})
.chain(default_instance.clone().map(|ident| (String::new(), ident)));
.chain(default_instance.clone().map(|ident| (String::new(), ident, quote! {#[doc=r"Default module instance"]})));

// Impl Instance trait for instances
for (prefix, ident) in instances {
for (prefix, ident, doc) in instances {
let mut const_impls = TokenStream2::new();

for (const_name, partial_const_value) in &const_names {
Expand All @@ -529,6 +530,7 @@ fn decl_storage_items(
// Those trait are derived because of wrong bounds for generics
#[cfg_attr(feature = "std", derive(Debug))]
#[derive(Clone, Eq, PartialEq, #scrate::codec::Encode, #scrate::codec::Decode)]
#doc
pub struct #ident;
impl #instantiable for #ident {
#const_impls
Expand Down
2 changes: 1 addition & 1 deletion srml/system/src/lib.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -124,8 +124,8 @@ pub struct EventRecord<E: Parameter + Member> {
pub event: E,
}

/// Event for the system module.
decl_event!(
/// Event for the system module.
pub enum Event {
/// An extrinsic completed successfully.
ExtrinsicSuccess,
Expand Down
10 changes: 1 addition & 9 deletions srml/treasury/src/lib.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,11 +31,6 @@ type BalanceOf<T> = <<T as Trait>::Currency as Currency<<T as system::Trait>::Ac
type PositiveImbalanceOf<T> = <<T as Trait>::Currency as Currency<<T as system::Trait>::AccountId>>::PositiveImbalance;
type NegativeImbalanceOf<T> = <<T as Trait>::Currency as Currency<<T as system::Trait>::AccountId>>::NegativeImbalance;

/// Our module's configuration trait. All our types and consts go in here. If the
/// module is dependent on specific other modules, then their configuration traits
/// should be added to our implied traits list.
///
/// `system::Trait` should always be included in our implied traits.
pub trait Trait: system::Trait {
/// The staking balance.
type Currency: Currency<Self::AccountId>;
Expand All @@ -58,10 +53,7 @@ pub trait Trait: system::Trait {

type ProposalIndex = u32;

// The module declaration. This states the entry points that we handle. The
// macro takes care of the marshalling of arguments and dispatch.
decl_module! {
// Simple declaration of the `Module` type. Lets the macro know what its working on.
pub struct Module<T: Trait> for enum Call where origin: T::Origin {
fn deposit_event<T>() = default;
/// Put forward a suggestion for spending. A deposit proportional to the value
Expand Down Expand Up @@ -177,8 +169,8 @@ decl_storage! {
}
}

/// An event in this module.
decl_event!(
/// An event in this module.
pub enum Event<T>
where
Balance = BalanceOf<T>,
Expand Down