Question - is there anything more fully developed around extrinsics documentation than this area in Polkadot JS?
It would be incredibly useful if there were an “extrinsicWiki” that detailed all of the calls, call combinations and curiosities as they arise in nice and easy human readable form - with examples, both established and imagined.
Given onchain governance / referendums / decision making is Substrate’s primary differentiator it seems like a major hole to not have something - unless I’m missing some existing resource.
I’m talking here about standard out of the box substrate runtime which still amounts to a large number of calls and call combinations.
I’m stumbling into call combinations through a fairly adhoc process involving digging through available docs, asking a range of people and generally just trying things out.
Duly noted, as a developer (key word “developer”), I always jump into the repo and look at the extrinsics in the pallet. For example, if I was interested in the NFTs pallet, I would go to the Substrate repo > frame > nfts > src > lib.rs and anything with a #[pallet::call_index(x)] index is an extrinsic. So for example, create:
/// Issue a new collection of non-fungible items from a public origin.
///
/// This new collection has no items initially and its owner is the origin.
///
/// The origin must be Signed and the sender must have sufficient funds free.
///
/// `ItemDeposit` funds of sender are reserved.
///
/// Parameters:
/// - `admin`: The admin of this collection. The admin is the initial address of each
/// member of the collection's admin team.
///
/// Emits `Created` event when successful.
///
/// Weight: `O(1)`
#[pallet::call_index(0)]
#[pallet::weight(T::WeightInfo::create())]
pub fn create(
Hey Rich! We also have a metadata explorer on the Polkadot Wiki that lets you dive deeper into the runtimes of Polkadot, Kusama, Asset Hubs and Rococo Metadata Explorer · Polkadot Wiki
Even as someone who does dev work, but not in substrate/rust, working out where the pallet code lives is non-trivial (or I’ve not worked out the magic path to follow to get to it). For example, I was just looking for the Open Gov pallet code. I think it might be pallet_referenda_referenda, but there’s no such pallet in the substrate marketplace or https://docs.substrate.io/ as far and I can see, and this seems related but doesn’t seem to cover the extrinsics: pallet_referenda - Rust. And I don’t even know where to start looking for the correct source control repo for it.
(This is more of a “this is the kind of issue people might have” comment, rather than a “please fix this issue for me personally” one. I found what I was looking for in the Moonbeam docs in the end.)
EDIT: Though it might be an eyesight failure on my part…
I’ve looked a bit into how to generate app developers (as opposed to network developers) focused documentation. So far this is the list of options I’ve found to start:
Metadata. As already mentioned the metadata is one source for building documentation. This has limits, but has improved with v15.
Rust Docs. Recent changes have added a way to export the rust docs as JSON now. So as long as the chain has good code level documentation (somewhat enforceable by cargo check), we are just missing a transformation between the cargo-doc json and the desired output.
(Mentioned above) HTML Rust docs are already generated for many chains, but are very focused on the Rust dev: https://paritytech.github.io/
Hand written. While these have an issue of being slow to update, extrinsics don’t change that often. That said it is easy to customize the data for a particular chain’s target audience and isn’t interjected with things that are important only for the Rust developers.
I have mostly been thinking about how to generate a nicer filtered and (likely markdown at the core) version of the docs from the rust docs JSON, but it has a TON of information to parse through. Or perhaps a poor version starting from this then shifting to human edited.
I am imagining something that sounds a bit like what you want. API style doc setup for application developers building on top of a chain (or chains).
Yes, though I’m actually thinking a little adjacent in my framing. So instead of “app developers” think about groups of people / collectives who are part of a small social network, who want to use / play around with extrinsics as part of some super-basic coordinating functions.
This group might then develop apps, but in its simplest form, I’m imagining extrinsic documentation for this kind of subset of users… I’m going to try and write an RFP to more clearly articulate what I’m thinking.
This is why I’m interested in quirks and oddities and “unlocking” weird combinations via Utility Batch etc
