diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.adoc similarity index 95% rename from CODE_OF_CONDUCT.md rename to CODE_OF_CONDUCT.adoc index 137f7ebe1a606..c5b21d93fb0c2 100644 --- a/CODE_OF_CONDUCT.md +++ b/CODE_OF_CONDUCT.adoc @@ -1,10 +1,10 @@ -# Contributor Covenant Code of Conduct += Contributor Covenant Code of Conduct -## Our Pledge +== Our Pledge In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, or sexual identity and orientation. -## Our Standards +== Our Standards Examples of behavior that contributes to creating a positive environment include: @@ -22,30 +22,30 @@ Examples of unacceptable behavior by participants include: * Publishing others' private information, such as a physical or electronic address, without explicit permission * Other conduct which could reasonably be considered inappropriate in a professional setting -### Facilitation, Not Strongarming +=== Facilitation, Not Strongarming We recognise that this software is merely a tool for users to create and maintain their blockchain of preference. We see that blockchains are naturally community platforms with users being the ultimate decision makers. We assert that good software will maximise user agency by facilitate user-expression on the network. As such: * This project will strive to give users as much choice as is both reasonable and possible over what protocol they adhere to; but * use of the project's technical forums, commenting systems, pull requests and issue trackers as a means to express individual protocol preferences is forbidden. -## Our Responsibilities +== Our Responsibilities Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior. Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful. -## Scope +== Scope This Code of Conduct applies both within project spaces and in public spaces when an individual is representing the project or its community. Examples of representing a project or community include using an official project e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. Representation of a project may be further defined and clarified by project maintainers. -## Enforcement +== Enforcement Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at admin@parity.io. The project team will review and investigate all complaints, and will respond in a way that it deems appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately. Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project's leadership. -## Attribution +== Attribution This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, available at [http://contributor-covenant.org/version/1/4][version] diff --git a/CONTRIBUTING.adoc b/CONTRIBUTING.adoc new file mode 100644 index 0000000000000..b789e03ed114c --- /dev/null +++ b/CONTRIBUTING.adoc @@ -0,0 +1,50 @@ += Contributing + +`Substrate` projects is a **OPENISH Open Source Project** + +== What? + +Individuals making significant and valuable contributions are given commit-access to a project to contribute as they see fit. A project is more like an open wiki than a standard guarded open source project. + +== Rules + +There are a few basic ground-rules for contributors (including the maintainer(s) of the project): + +. **No `--force` pushes** or modifying the Git history in any way. If you need to rebase, ensure you do it in your own repo. +. **Non-master branches**, prefixed with a short name moniker (e.g. `gav-my-feature`) must be used for ongoing work. +. **All modifications** must be made in a **pull-request** to solicit feedback from other contributors. +. A pull-request *must not be merged until CI* has finished successfully. +. Contributors should adhere to the https://github.com/paritytech/polkadot/wiki/Style-Guide[house coding style]. + +Merging pull requests once CI is successful: + +. A pull request that does not alter any logic (e.g. comments, dependencies, docs) may be tagged https://github.com/paritytech/substrate/pulls?utf8=%E2%9C%93&q=is%3Apr+is%3Aopen+label%3AA2-insubstantial[`insubstantial`] and merged by its author. +. A pull request with no large change to logic that is an urgent fix may be merged after a non-author contributor has reviewed it well. +. All other PRs should sit for 48 hours with the https://github.com/paritytech/substrate/pulls?q=is%3Apr+is%3Aopen+label%3AA0-pleasereview[`pleasereview`] tag in order to garner feedback. +. No PR should be merged until all reviews' comments are addressed. + +.Reviewing pull requests: +When reviewing a pull request, the end-goal is to suggest useful changes to the author. Reviews should finish with approval unless there are issues that would result in: + +. Buggy behaviour. +. Undue maintenance burden. +. Breaking with house coding style. +. Pessimisation (i.e. reduction of speed as measured in the projects benchmarks). +. Feature reduction (i.e. it removes some aspect of functionality that a significant minority of users rely on). +. Uselessness (i.e. it does not strictly add a feature or fix a known issue). + +.Reviews may not be used as an effective veto for a PR because: +. There exists a somewhat cleaner/better/faster way of accomplishing the same feature/fix. +. It does not fit well with some other contributors' longer-term vision for the project. + +== Releases + +Declaring formal releases remains the prerogative of the project maintainer(s). + +== Changes to this arrangement + +This is an experiment and feedback is welcome! This document may also be subject to pull-requests or changes by contributors where you believe you have something valuable to add or change. + +== Heritage + +These contributing guidelines are modified from the "OPEN Open Source Project" guidelines for the Level project: https://github.com/Level/community/blob/master/CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md deleted file mode 100644 index 4f89f5d539139..0000000000000 --- a/CONTRIBUTING.md +++ /dev/null @@ -1,53 +0,0 @@ -## `Substrate` projects is a **OPENISH Open Source Project** ------------------------------------------ - -## What? - -Individuals making significant and valuable contributions are given commit-access to a project to contribute as they see fit. A project is more like an open wiki than a standard guarded open source project. - -## Rules - -There are a few basic ground-rules for contributors (including the maintainer(s) of the project): - -1. **No `--force` pushes** or modifying the Git history in any way. If you need to rebase, ensure you do it in your own repo. -1. **Non-master branches**, prefixed with a short name moniker (e.g. `gav-my-feature`) must be used for ongoing work. -1. **All modifications** must be made in a **pull-request** to solicit feedback from other contributors. -1. A pull-request *must not be merged until CI* has finished successfully. -1. Contributors should adhere to the [house coding style](https://github.com/paritytech/polkadot/wiki/Style-Guide). - -Merging pull requests once CI is successful: - -1. A pull request that does not alter any logic (e.g. comments, dependencies, docs) may be tagged [`insubstantial`](https://github.com/paritytech/polkadot/pulls?utf8=%E2%9C%93&q=is%3Apr+is%3Aopen+label%3AA2-insubstantial+) and merged by its author. -1. A pull request with no large change to logic that is an urgent fix may be merged after a non-author contributor has reviewed it well. -1. All other PRs should sit for 48 hours with the [`pleasereview`](https://github.com/paritytech/polkadot/pulls?q=is%3Apr+is%3Aopen+label%3AA0-pleasereview) tag in order to garner feedback. -1. No PR should be merged until all reviews' comments are addressed. - -Reviewing pull requests: - -When reviewing a pull request, the end-goal is to suggest useful changes to the author. Reviews should finish with approval unless there are issues that would result in: - -1. Buggy behaviour. -1. Undue maintenance burden. -1. Breaking with house coding style. -1. Pessimisation (i.e. reduction of speed as measured in the projects benchmarks). -1. Feature reduction (i.e. it removes some aspect of functionality that a significant minority of users rely on). -1. Uselessness (i.e. it does not strictly add a feature or fix a known issue). - -Reviews may not be used as an effective veto for a PR because: - -1. There exists a somewhat cleaner/better/faster way of accomplishing the same feature/fix. -1. It does not fit well with some other contributors' longer-term vision for the project. - -## Releases - -Declaring formal releases remains the prerogative of the project maintainer(s). - -## Changes to this arrangement - -This is an experiment and feedback is welcome! This document may also be subject to pull-requests or changes by contributors where you believe you have something valuable to add or change. - -## Heritage - -These contributing guidelines are modified from the "OPEN Open Source Project" guidelines for the Level project: https://github.com/Level/community/blob/master/CONTRIBUTING.md - ------------------------------------------ diff --git a/README.adoc b/README.adoc index 59f9f64096012..f1502ca3313fc 100644 --- a/README.adoc +++ b/README.adoc @@ -1,14 +1,20 @@ -# Substrate += Substrate +:Author: Polkadot developers +:Revision: 0.2.0 +:toc: +:sectnums: + +== Intro Next-generation framework for blockchain innovation. -## Description +== Description At its heart, Substrate is a combination of three technologies: WebAssembly, Libp2p and AfG Consensus. It is both a library for building new blockchains and a "skeleton key" of a blockchain client, able to synchronise to any Substrate-based chain. Substrate chains have three distinct features that make them "next-generation": a dynamic, self-defining state-transition function, light-client functionality from day one and a progressive consensus algorithm with fast block production and adaptive, definite finality. The STF, encoded in WebAssembly, is known as the "runtime". This defines the `execute_block` function, and can specify everything from the staking algorithm, transaction semantics, logging mechanisms and procedures for replacing any aspect of itself or of the blockchain's state ("governance"). Because the runtime is entirely dynamic all of these can be switched out or upgraded at any time. A Substrate chain is very much a "living organism". -## Usage +== Usage Substrate is still an early stage project, and while it has already been used as the basis of major projects like Polkadot, using it is still a significant undertaking. In particular, you should have a good knowledge of blockchain concepts and basic cryptography. Terminology like header, block, client, hash, transaction and signature should be familiar. At present you will need a working knowledge of Rust to be able to do anything interesting (though eventually, we aim for this not to be the case). @@ -20,16 +26,16 @@ Substrate is designed to be used in one of three ways: 3. Generic: The entire Substrate Runtime Module Library can be ignored and the entire runtime designed and implemented from scratch. If desired, this can be done in a language other than Rust, providing it can target WebAssembly. If the runtime can be made to be compatible with the existing client's block authoring logic, then you can simply construct a new genesis block from your Wasm blob and launch your chain with the existing Rust-based Substrate client. If not, then you'll need to alter the client's block authoring logic accordingly. This is probably a useless option for most projects right now, but provides complete flexibility allowing for a long-term far-reaching upgrade path for the Substrate paradigm. -### The Basics of Substrate +=== The Basics of Substrate -Substrate is a blockchain platform with a completely generic state transition function. That said, it does come with both standards and conventions (particularly regarding the Runtime Module Library) regarding underlying datastructures. Roughly speaking, these core datatypes correspond to as `trait`s in terms of the actual non-negotiable standard and generic `struct`s in terms of the convention. +Substrate is a blockchain platform with a completely generic state transition function. That said, it does come with both standards and conventions (particularly regarding the Runtime Module Library) regarding underlying datastructures. Roughly speaking, these core datatypes correspond to as +trait+s in terms of the actual non-negotiable standard and generic +struct+s in terms of the convention. ``` Header := Parent + ExtrinsicsRoot + StorageRoot + Digest Block := Header + Extrinsics + Justifications ``` -### Extrinsics +=== Extrinsics Extrinsics in Substrate are pieces of information from "the outside world" that are contained in the blocks of the chain. You might think "ahh, that means *transactions*": in fact, no. Extrinsics fall into two broad categories of which only one is *transactions*. The other is known as *inherents*. The difference between these two is that transactions are signed and gossipped on the network and can be deemed useful *per se*. This fits the mould of what you would call transactions in Bitcoin or Ethereum. @@ -39,7 +45,8 @@ To give an example, there is the timestamp inherent which sets the current times Other examples include the parachain-heads extrinsic in Polkadot and the "note-missed-proposal" extrinsic used in the Substrate Runtime Module Library to determine and punish or deactivate offline validators. -### Runtime and API + +=== Runtime and API Substrate chains all have a runtime. The runtime is a WebAssembly "blob" that includes a number of entry-points. Some entry-points are required as part of the underlying Substrate specification. Others are merely convention and required for the default implemnentation of the Substrate client to be able to author blocks. In short these two sets are: @@ -72,13 +79,13 @@ pub mod api { As you can see, at the minimum there are only three API calls to implement. If you want to reuse as much of Substrate's reference block authoring client code, then you'll want to provide the next four entrypoints (though three of them you probably already implemented as part of `execute_block`). -Of the first three, there is `execute_block`, which contains the actions to be taken to execute a block and pretty much defines the blockchain. Then there is `authorities` which tells the AfG consensus algorithm sitting in the Substrate client who the given authorities (known as "validators" in some contexts) are that can finalise the next block. Finally, there is `version`, which is a fairly sophisticated version identifier. This includes a key distinction between *specification version* and *authoring version*, with the former essentially versioning the logic of `execute_block` and the latter versioning only the logic of `inherent_extrinsics` and core aspects of extrinsic validity. +Of the first three, there is `execute_block`, which contains the actions to be taken to execute a block and pretty much defines the blockchain. Then there is `authorities` which tells the AfG consensus algorithm sitting in the Substrate client who the given authorities (known as "validators" in some contexts) are that can finalise the next block. Finally, there is `version`, which is a fairly sophisticated version identifier. This includes a key distinction between *specification version* and *authoring version*, with the former essentially versioning the logic of `execute_block` and the latter versioning only the logic of `inherent_extrinsics` and core aspects of extrinsic validity. -### Inherent Extrinsics +=== Inherent Extrinsics The Substrate Runtime Module Library includes functionality for timestamps and slashing. If used, these rely on "trusted" external information being passed in via inherent extrinsics. The Substrate reference block authoring client software will expect to be able to call into the runtime API with collated data (in the case of the reference Substrate authoring client, this is merely the current timestamp and which nodes were offline) in order to return the appropriate extrinsics ready for inclusion. If new inherent extrinsic types and data are to be used in a modified runtime, then it is this function (and its argument type) that would change. -### Block-authoring Logic +=== Block-authoring Logic In Substrate, there is a major distinction between blockchain *syncing* and block *authoring* ("authoring" is a more general term for what is called "mining" in Bitcoin). The first case might be refered to as a "full node" (or "light node" - Substrate supports both): authoring necessarily requires a synced node and therefore all authoring clients must necessarily be able to synchronise. However, the reverse is not true. The primary functionality that authoring nodes have which is not in "sync nodes" is threefold: transaction queue logic, inherent transaction knowledge and BFT consensus logic. BFT consensus logic is provided as a core element of Substrate and can be ignored since it is only exposed in the SDK under the `authorities()` API entry. @@ -86,20 +93,20 @@ Transaction queue logic in Substrate is designed to be as generic as possible, a Inherent extrinsic knowledge is again somewhat generic, and the actual construction of the extrinsics is, by convention, delegated to the "soft code" in the runtime. If ever there needs to be additional extrinsic information in the chain, then both the block authoring logic will need to be altered to provide it into the runtime and the runtime's `inherent_extrinsics` call will need to use this extra information in order to construct any additional extrinsic transactions for inclusion in the block. -## Roadmap +== Roadmap -### So far +=== So far - 0.1 "PoC-1": PBFT consensus, Wasm runtime engine, basic runtime modules. - 0.2 "PoC-2": Libp2p -### In progress +=== In progress - AfG consensus - Improved PoS - Smart contract runtime module -### The future +=== The future - Splitting out runtime modules into separate repo - Introduce substrate executable (the skeleton-key runtime) @@ -108,9 +115,9 @@ Inherent extrinsic knowledge is again somewhat generic, and the actual construct - Audit -## Building +== Building -== Hacking on Substrate +=== Hacking on Substrate If you'd actually like hack on Substrate, you can just grab the source code and build it. Ensure you have Rust and the support software installed: @@ -137,9 +144,9 @@ Then build the code: [source, shell] ---- -./scripts/build.sh # Builds the WebAssembly binaries -./scripts/build-demos.sh # Builds the WebAssembly binaries -cargo build # Builds all native code +./scripts/build.sh # Builds the WebAssembly binaries +./scripts/build-demos.sh # Builds the WebAssembly binaries +cargo build # Builds all native code ---- You can run the tests if you like: @@ -152,26 +159,13 @@ You can start a development chain with: [source, shell] cargo run -- --dev -=== Development - -You can run a simple single-node development "network" on your machine by -running in a terminal: - -[source, shell] -substrate --dev - -== Local Two-node Testnet +include::doc/packages/packages.adoc[] -If you want to see the multi-node consensus algorithm in action locally, then -you can create a local testnet. You'll need two terminals open. In one, run: +include::CONTRIBUTING.adoc[leveloffset=+1] -[source, shell] -substrate --chain=local --validator --key Alice -d /tmp/alice - -and in the other, run: - -[source, shell] -substrate --chain=local --validator --key Bob -d /tmp/bob --port 30334 --bootnodes '/ip4/127.0.0.1/tcp/30333/p2p/ALICE_BOOTNODE_ID_HERE' +include::CODE_OF_CONDUCT.adoc[leveloffset=+1] -Ensure you replace `ALICE_BOOTNODE_ID_HERE` with the node ID from the output of -the first terminal. +== License +---- +include::LICENSE[] +---- diff --git a/doc/packages.adoc b/doc/packages.adoc deleted file mode 100644 index f21c307077a98..0000000000000 --- a/doc/packages.adoc +++ /dev/null @@ -1,33 +0,0 @@ - -== Cargo Packages - -:leveloffset: +2 - -include::../polkadot/api/README.adoc[] - -include::../polkadot/cli/README.adoc[] - -include::../polkadot/collator/README.adoc[] - -include::../polkadot/consensus/README.adoc[] - -include::../polkadot/executor/README.adoc[] - -include::../polkadot/network/README.adoc[] - -include::../polkadot/parachain/README.adoc[] - -include::../polkadot/primitives/README.adoc[] - -include::../polkadot/runtime/README.adoc[] - -include::../polkadot/service/README.adoc[] - -include::../polkadot/src/README.adoc[] - -include::../polkadot/statement-table/README.adoc[] - -include::../polkadot/transaction-pool/README.adoc[] - -:leveloffset: -2 - diff --git a/doc/packages/misc.adoc b/doc/packages/misc.adoc new file mode 100644 index 0000000000000..316cf44858c91 --- /dev/null +++ b/doc/packages/misc.adoc @@ -0,0 +1,10 @@ + +=== Misc packages + +:leveloffset: +3 + +include::../../safe-mix/README.adoc[] + +include::../../subkey/README.adoc[] + +:leveloffset: -3 diff --git a/doc/packages/packages.adoc b/doc/packages/packages.adoc new file mode 100644 index 0000000000000..aa95bb1f934a8 --- /dev/null +++ b/doc/packages/packages.adoc @@ -0,0 +1,4 @@ + +include::substrate.adoc[] + +include::misc.adoc[] diff --git a/doc/packages/substrate.adoc b/doc/packages/substrate.adoc new file mode 100644 index 0000000000000..75f391e2b6409 --- /dev/null +++ b/doc/packages/substrate.adoc @@ -0,0 +1,66 @@ + +== Substrate Packages + +:leveloffset: +3 + +include::../../substrate/bft/README.adoc[] + +include::../../substrate/cli/README.adoc[] + +include::../../substrate/client/README.adoc[] + +include::../../substrate/codec/README.adoc[] + +include::../../substrate/ed25519/README.adoc[] + +include::../../substrate/environmental/README.adoc[] + +include::../../substrate/executor/README.adoc[] + +include::../../substrate/extrinsic-pool/README.adoc[] + +include::../../substrate/keyring/README.adoc[] + +include::../../substrate/keystore/README.adoc[] + +include::../../substrate/misbehavior-check/README.adoc[] + +include::../../substrate/network/README.adoc[] + +include::../../substrate/network-libp2p/README.adoc[] + +include::../../substrate/primitives/README.adoc[] + +include::../../substrate/pwasm-alloc/README.adoc[] + +include::../../substrate/pwasm-libc/README.adoc[] + +include::../../substrate/rpc/README.adoc[] + +include::../../substrate/rpc-servers/README.adoc[] + +include::../../substrate/runtime/README.adoc[] + +include::../../substrate/runtime-io/README.adoc[] + +include::../../substrate/runtime-sandbox/README.adoc[] + +include::../../substrate/runtime-std/README.adoc[] + +include::../../substrate/runtime-support/README.adoc[] + +include::../../substrate/serializer/README.adoc[] + +include::../../substrate/service/README.adoc[] + +include::../../substrate/state-db/README.adoc[] + +include::../../substrate/state-machine/README.adoc[] + +include::../../substrate/telemetry/README.adoc[] + +include::../../substrate/test-client/README.adoc[] + +include::../../substrate/test-runtime/README.adoc[] + +:leveloffset: -3 diff --git a/safe-mix/README.adoc b/safe-mix/README.adoc new file mode 100644 index 0000000000000..074b2496d03f4 --- /dev/null +++ b/safe-mix/README.adoc @@ -0,0 +1,5 @@ += Safe-mix + +Means of mixing a series of hashes to create a single secure hash. + +Described in http://www.cs.huji.ac.il/~nati/PAPERS/coll_coin_fl.pdf diff --git a/substrate/bft/README.adoc b/substrate/bft/README.adoc new file mode 100644 index 0000000000000..8f4939087eed7 --- /dev/null +++ b/substrate/bft/README.adoc @@ -0,0 +1,13 @@ + += Substrate BFT + +.Summary +[source, toml] +---- +include::Cargo.toml[lines=2..5] +---- + +.Description +---- +include::src/lib.rs[tag=description] +---- diff --git a/substrate/bft/src/lib.rs b/substrate/bft/src/lib.rs index 9e465f852cec7..40440143a3a90 100644 --- a/substrate/bft/src/lib.rs +++ b/substrate/bft/src/lib.rs @@ -14,6 +14,7 @@ // You should have received a copy of the GNU General Public License // along with Substrate. If not, see . +// tag::description[] //! BFT Agreement based on a rotating proposer in different rounds. //! //! Where this crate refers to input stream, should never logically conclude. @@ -29,6 +30,7 @@ //! conclude without having witnessed the conclusion. //! In general, this future should be pre-empted by the import of a justification //! set for this block height. +// end::description[] #![recursion_limit="128"] diff --git a/substrate/cli/README.adoc b/substrate/cli/README.adoc index 1ad1d01eb1330..2b9b74362d322 100644 --- a/substrate/cli/README.adoc +++ b/substrate/cli/README.adoc @@ -1,11 +1,13 @@ = Substrate CLI -== Summary - +.Summary [source, toml] ---- include::Cargo.toml[lines=2..5] ---- +.Description +Polkadot CLI library + include::doc/shell-completion.adoc[] diff --git a/substrate/cli/src/lib.rs b/substrate/cli/src/lib.rs index 6322bb22fe930..94d8849b05b35 100644 --- a/substrate/cli/src/lib.rs +++ b/substrate/cli/src/lib.rs @@ -14,7 +14,9 @@ // You should have received a copy of the GNU General Public License // along with Substrate. If not, see . +// tag::description[] //! Substrate CLI library. +// end::description[] #![warn(missing_docs)] #![warn(unused_extern_crates)] diff --git a/substrate/client/README.adoc b/substrate/client/README.adoc new file mode 100644 index 0000000000000..d644b1d039b11 --- /dev/null +++ b/substrate/client/README.adoc @@ -0,0 +1,13 @@ + += Client + +.Summary +[source, toml] +---- +include::Cargo.toml[lines=2..5] +---- + +.Description +---- +include::src/lib.rs[tag=description] +---- diff --git a/substrate/client/db/src/lib.rs b/substrate/client/db/src/lib.rs index e7b7fb5deffef..c4911e7d9c6d8 100644 --- a/substrate/client/db/src/lib.rs +++ b/substrate/client/db/src/lib.rs @@ -14,7 +14,9 @@ // You should have received a copy of the GNU General Public License // along with Substrate. If not, see . +// tag::description[] //! Client backend that uses RocksDB database as storage. +// end::description[] extern crate substrate_client as client; extern crate kvdb_rocksdb; diff --git a/substrate/codec/README.adoc b/substrate/codec/README.adoc new file mode 100644 index 0000000000000..12d3953789a0a --- /dev/null +++ b/substrate/codec/README.adoc @@ -0,0 +1,13 @@ + += Codec + +.Summary +[source, toml] +---- +include::Cargo.toml[lines=2..5] +---- + +.Description +---- +include::src/lib.rs[tag=description] +---- diff --git a/substrate/codec/src/lib.rs b/substrate/codec/src/lib.rs index d4a0843f0a657..c1c29ccaa0abc 100644 --- a/substrate/codec/src/lib.rs +++ b/substrate/codec/src/lib.rs @@ -14,7 +14,9 @@ // You should have received a copy of the GNU General Public License // along with Substrate. If not, see . +// tag::description[] //! Implements a serialization and deserialization codec for simple marshalling. +// end::description[] #![cfg_attr(not(feature = "std"), no_std)] #![cfg_attr(not(feature = "std"), feature(alloc))] diff --git a/substrate/ed25519/README.adoc b/substrate/ed25519/README.adoc new file mode 100644 index 0000000000000..97c10769ee902 --- /dev/null +++ b/substrate/ed25519/README.adoc @@ -0,0 +1,13 @@ + += ED25519 + +.Summary +[source, toml] +---- +include::Cargo.toml[lines=2..5] +---- + +.Description +---- +include::src/lib.rs[tag=description] +---- diff --git a/substrate/ed25519/src/lib.rs b/substrate/ed25519/src/lib.rs index e02108524604b..a7f419f47842c 100644 --- a/substrate/ed25519/src/lib.rs +++ b/substrate/ed25519/src/lib.rs @@ -14,7 +14,9 @@ // You should have received a copy of the GNU General Public License // along with Substrate. If not, see . +// tag::description[] //! Simple Ed25519 API. +// end::description[] extern crate ring; extern crate base58; diff --git a/substrate/environmental/README.adoc b/substrate/environmental/README.adoc new file mode 100644 index 0000000000000..b12a0f9f5fad6 --- /dev/null +++ b/substrate/environmental/README.adoc @@ -0,0 +1,13 @@ + += Environmental + +.Summary +[source, toml] +---- +include::Cargo.toml[lines=2..5] +---- + +.Description +---- +include::src/lib.rs[tag=description] +---- diff --git a/substrate/environmental/src/lib.rs b/substrate/environmental/src/lib.rs index f6f0e94c74522..094bd536655e1 100644 --- a/substrate/environmental/src/lib.rs +++ b/substrate/environmental/src/lib.rs @@ -14,6 +14,7 @@ // You should have received a copy of the GNU General Public License // along with Substrate. If not, see . +// tag::description[] //! Safe global references to stack variables. //! //! Set up a global reference with environmental! macro giving it a name and type. @@ -39,6 +40,7 @@ //! stuff(); // safe! doesn't do anything. //! } //! ``` +// end::description[] #![cfg_attr(not(feature = "std"), no_std)] #![cfg_attr(not(feature = "std"), feature(const_fn))] diff --git a/substrate/executor/README.adoc b/substrate/executor/README.adoc new file mode 100644 index 0000000000000..6a0ee23565a70 --- /dev/null +++ b/substrate/executor/README.adoc @@ -0,0 +1,13 @@ + += Executor + +.Summary +[source, toml] +---- +include::Cargo.toml[lines=2..5] +---- + +.Description +---- +include::src/lib.rs[tag=description] +---- diff --git a/substrate/executor/src/lib.rs b/substrate/executor/src/lib.rs index 57f48cd6ed063..cee6107fdd562 100644 --- a/substrate/executor/src/lib.rs +++ b/substrate/executor/src/lib.rs @@ -14,6 +14,7 @@ // You should have received a copy of the GNU General Public License // along with Substrate. If not, see . +// tag::description[] //! Temporary crate for contracts implementations. //! //! This will be replaced with WASM contracts stored on-chain. @@ -24,6 +25,7 @@ //! - init_block(PrevBlock?) -> InProgressBlock //! - add_transaction(InProgressBlock) -> InProgressBlock //! I leave it as is for now as it might be removed before this is ever done. +// end::description[] #![warn(missing_docs)] #![recursion_limit="128"] diff --git a/substrate/extrinsic-pool/README.adoc b/substrate/extrinsic-pool/README.adoc new file mode 100644 index 0000000000000..e128d64c9bf8b --- /dev/null +++ b/substrate/extrinsic-pool/README.adoc @@ -0,0 +1,13 @@ + += extrinsic-pool + +.Summary +[source, toml] +---- +include::Cargo.toml[lines=2..5] +---- + +.Description +---- +include::src/lib.rs[tag=description] +---- diff --git a/substrate/extrinsic-pool/src/lib.rs b/substrate/extrinsic-pool/src/lib.rs index 1de16b02dad04..bcd2b03c80e00 100644 --- a/substrate/extrinsic-pool/src/lib.rs +++ b/substrate/extrinsic-pool/src/lib.rs @@ -14,11 +14,13 @@ // You should have received a copy of the GNU General Public License // along with Substrate. If not, see . +// tag::description[] +//! Generic extrinsic pool. +// end::description[] + #![warn(missing_docs)] #![warn(unused_extern_crates)] -//! Generic extrinsic pool. - extern crate futures; extern crate parking_lot; extern crate substrate_runtime_primitives as runtime_primitives; diff --git a/substrate/keyring/README.adoc b/substrate/keyring/README.adoc new file mode 100644 index 0000000000000..0118fe883d1a6 --- /dev/null +++ b/substrate/keyring/README.adoc @@ -0,0 +1,13 @@ + += Keyring + +.Summary +[source, toml] +---- +include::Cargo.toml[lines=2..5] +---- + +.Description +---- +include::src/lib.rs[tag=description] +---- diff --git a/substrate/keyring/src/lib.rs b/substrate/keyring/src/lib.rs index e7700071102ad..6f0270c9d4de9 100644 --- a/substrate/keyring/src/lib.rs +++ b/substrate/keyring/src/lib.rs @@ -14,7 +14,9 @@ // You should have received a copy of the GNU General Public License // along with Substrate. If not, see . +// tag::description[] //! Support code for the runtime. +// end::description[] #[macro_use] extern crate hex_literal; #[macro_use] extern crate lazy_static; diff --git a/substrate/keystore/README.adoc b/substrate/keystore/README.adoc new file mode 100644 index 0000000000000..5a66a882ff098 --- /dev/null +++ b/substrate/keystore/README.adoc @@ -0,0 +1,13 @@ + += Keystore + +.Summary +[source, toml] +---- +include::Cargo.toml[lines=2..5] +---- + +.Description +---- +include::src/lib.rs[tag=description] +---- diff --git a/substrate/keystore/src/lib.rs b/substrate/keystore/src/lib.rs index 015cad74e9c48..af261a35109b3 100644 --- a/substrate/keystore/src/lib.rs +++ b/substrate/keystore/src/lib.rs @@ -14,7 +14,9 @@ // You should have received a copy of the GNU General Public License // along with Substrate. If not, see . +// tag::description[] //! Keystore (and session key management) for ed25519 based chains like Polkadot. +// end::description[] extern crate parity_crypto as crypto; extern crate subtle; diff --git a/substrate/misbehavior-check/README.adoc b/substrate/misbehavior-check/README.adoc new file mode 100644 index 0000000000000..e5b52b954b673 --- /dev/null +++ b/substrate/misbehavior-check/README.adoc @@ -0,0 +1,13 @@ + += Misbehavior-check + +.Summary +[source, toml] +---- +include::Cargo.toml[lines=2..5] +---- + +.Description +---- +include::src/lib.rs[tag=description] +---- diff --git a/substrate/misbehavior-check/src/lib.rs b/substrate/misbehavior-check/src/lib.rs index 7c30407844cbd..eff87ab1e5efb 100644 --- a/substrate/misbehavior-check/src/lib.rs +++ b/substrate/misbehavior-check/src/lib.rs @@ -14,7 +14,9 @@ // You should have received a copy of the GNU General Public License // along with Substrate. If not, see . +// tag::description[] //! Utility for substrate-based runtimes that want to check misbehavior reports. +// end::description[] #![cfg_attr(not(feature = "std"), no_std)] diff --git a/substrate/network-libp2p/README.adoc b/substrate/network-libp2p/README.adoc new file mode 100644 index 0000000000000..2f340aa397e73 --- /dev/null +++ b/substrate/network-libp2p/README.adoc @@ -0,0 +1,13 @@ + += Network libp2p + +.Summary +[source, toml] +---- +include::Cargo.toml[lines=2..5] +---- + +.Description +---- +include::src/lib.rs[tag=description] +---- diff --git a/substrate/network-libp2p/src/lib.rs b/substrate/network-libp2p/src/lib.rs index 59d056b969689..f06c8fefd865f 100644 --- a/substrate/network-libp2p/src/lib.rs +++ b/substrate/network-libp2p/src/lib.rs @@ -14,6 +14,10 @@ // You should have received a copy of the GNU General Public License // along with Substrate. If not, see . +// tag::description[] +//! TODO: Missing doc +// end::description[] + #![recursion_limit="128"] #![type_length_limit = "268435456"] diff --git a/substrate/network/README.adoc b/substrate/network/README.adoc new file mode 100644 index 0000000000000..ac29b0cd0bfbc --- /dev/null +++ b/substrate/network/README.adoc @@ -0,0 +1,13 @@ + += Network + +.Summary +[source, toml] +---- +include::Cargo.toml[lines=2..5] +---- + +.Description +---- +include::src/lib.rs[tag=description] +---- diff --git a/substrate/network/src/lib.rs b/substrate/network/src/lib.rs index 2cee2de47e29e..14d3d82da5dbc 100644 --- a/substrate/network/src/lib.rs +++ b/substrate/network/src/lib.rs @@ -17,8 +17,10 @@ #![warn(unused_extern_crates)] #![warn(missing_docs)] +// tag::description[] //! Substrate-specific P2P networking: synchronizing blocks, propagating BFT messages. //! Allows attachment of an optional subprotocol for chain-specific requests. +// end::description[] extern crate ethcore_io as core_io; extern crate linked_hash_map; diff --git a/substrate/primitives/README.adoc b/substrate/primitives/README.adoc new file mode 100644 index 0000000000000..ed98cf12adf1f --- /dev/null +++ b/substrate/primitives/README.adoc @@ -0,0 +1,13 @@ + += Primitives + +.Summary +[source, toml] +---- +include::Cargo.toml[lines=2..5] +---- + +.Description +---- +include::src/lib.rs[tag=description] +---- diff --git a/substrate/primitives/src/lib.rs b/substrate/primitives/src/lib.rs index 668cca6b7a921..7ba9a054ceef4 100644 --- a/substrate/primitives/src/lib.rs +++ b/substrate/primitives/src/lib.rs @@ -14,7 +14,9 @@ // You should have received a copy of the GNU General Public License // along with Substrate. If not, see . +// tag::description[] //! Shareable Polkadot types. +// end::description[] #![warn(missing_docs)] diff --git a/substrate/pwasm-alloc/README.adoc b/substrate/pwasm-alloc/README.adoc new file mode 100644 index 0000000000000..5ddc97ea1b901 --- /dev/null +++ b/substrate/pwasm-alloc/README.adoc @@ -0,0 +1,25 @@ + += Pwasm-alloc + +Parity WASM contracts standard library libc bindings. + +See https://paritytech.github.io/pwasm-std/pwasm_alloc/ for the documentation. + +== License + +`pwasm_alloc` is primarily distributed under the terms of both the MIT +license and the Apache License (Version 2.0), at your choice. + +See LICENSE-APACHE, and LICENSE-MIT for details. + +.Summary +[source, toml] +---- +include::Cargo.toml[lines=2..5] +---- + +.Description +---- +include::src/lib.rs[tag=description] +---- + diff --git a/substrate/pwasm-alloc/README.md b/substrate/pwasm-alloc/README.md deleted file mode 100644 index 489d629bc10b5..0000000000000 --- a/substrate/pwasm-alloc/README.md +++ /dev/null @@ -1,12 +0,0 @@ -# pwasm-libc - -Parity WASM contracts standard library libc bindings - -[Documentation](https://paritytech.github.io/pwasm-std/pwasm_alloc/) - -# License - -`pwasm_alloc` is primarily distributed under the terms of both the MIT -license and the Apache License (Version 2.0), at your choice. - -See LICENSE-APACHE, and LICENSE-MIT for details. diff --git a/substrate/pwasm-alloc/src/lib.rs b/substrate/pwasm-alloc/src/lib.rs index 7dbfb562a91d1..b08eef6854808 100644 --- a/substrate/pwasm-alloc/src/lib.rs +++ b/substrate/pwasm-alloc/src/lib.rs @@ -3,7 +3,9 @@ #![no_std] #![crate_type = "rlib"] +// tag::description[] //! Custom allocator crate for wasm +// end::description[] /// Wasm allocator pub struct WasmAllocator; diff --git a/substrate/pwasm-libc/README.md b/substrate/pwasm-libc/README.adoc similarity index 52% rename from substrate/pwasm-libc/README.md rename to substrate/pwasm-libc/README.adoc index b01c4a76707eb..e1cba6632f1df 100644 --- a/substrate/pwasm-libc/README.md +++ b/substrate/pwasm-libc/README.adoc @@ -1,12 +1,24 @@ -# pwasm-libc + += Pwasm-libc Parity WASM contracts standard library libc bindings -[Documentation](https://paritytech.github.io/pwasm-std/pwasm_libc/) +https://paritytech.github.io/pwasm-std/pwasm_libc/[Documentation] -# License +== License `pwasm-libc` is primarily distributed under the terms of both the MIT license and the Apache License (Version 2.0), at your choice. See LICENSE-APACHE, and LICENSE-MIT for details. + +.Summary +[source, toml] +---- +include::Cargo.toml[lines=2..5] +---- + +.Description +---- +include::src/lib.rs[tag=description] +---- diff --git a/substrate/pwasm-libc/src/lib.rs b/substrate/pwasm-libc/src/lib.rs index f4e5eb7a57455..6b97ff378890b 100644 --- a/substrate/pwasm-libc/src/lib.rs +++ b/substrate/pwasm-libc/src/lib.rs @@ -2,7 +2,9 @@ #![cfg_attr(feature = "strict", deny(warnings))] #![no_std] +// tag::description[] //! libc externs crate +// end::description[] extern "C" { fn ext_memcpy(dest: *mut u8, src: *const u8, n: usize) -> *mut u8; diff --git a/substrate/rpc-servers/README.adoc b/substrate/rpc-servers/README.adoc new file mode 100644 index 0000000000000..18840be421fdd --- /dev/null +++ b/substrate/rpc-servers/README.adoc @@ -0,0 +1,14 @@ + += RPC Server + +.Summary +[source, toml] +---- +include::Cargo.toml[lines=2..5] +---- + +.Description +---- +include::src/lib.rs[tag=description] +---- + diff --git a/substrate/rpc-servers/src/lib.rs b/substrate/rpc-servers/src/lib.rs index 530d637f096d0..6139d32aec963 100644 --- a/substrate/rpc-servers/src/lib.rs +++ b/substrate/rpc-servers/src/lib.rs @@ -14,7 +14,9 @@ // You should have received a copy of the GNU General Public License // along with Substrate. If not, see . +// tag::description[] //! Substrate RPC servers. +// end::description[] #[warn(missing_docs)] diff --git a/substrate/rpc/README.adoc b/substrate/rpc/README.adoc new file mode 100644 index 0000000000000..5e4db4909976a --- /dev/null +++ b/substrate/rpc/README.adoc @@ -0,0 +1,13 @@ + += RPC + +.Summary +[source, toml] +---- +include::Cargo.toml[lines=2..5] +---- + +.Description +---- +include::src/lib.rs[tag=description] +---- diff --git a/substrate/rpc/src/lib.rs b/substrate/rpc/src/lib.rs index 760b1ca567263..fe949c226c227 100644 --- a/substrate/rpc/src/lib.rs +++ b/substrate/rpc/src/lib.rs @@ -14,7 +14,9 @@ // You should have received a copy of the GNU General Public License // along with Substrate. If not, see . +// tag::description[] //! Substrate RPC interfaces. +// end::description[] #![warn(missing_docs)] diff --git a/substrate/runtime-io/README.adoc b/substrate/runtime-io/README.adoc new file mode 100644 index 0000000000000..c035be1461188 --- /dev/null +++ b/substrate/runtime-io/README.adoc @@ -0,0 +1,13 @@ + += Runtime io + +.Summary +[source, toml] +---- +include::Cargo.toml[lines=2..5] +---- + +.Description +---- +include::src/lib.rs[tag=description] +---- diff --git a/substrate/runtime-io/src/lib.rs b/substrate/runtime-io/src/lib.rs index 88446c21e804d..9214a7aa37b98 100644 --- a/substrate/runtime-io/src/lib.rs +++ b/substrate/runtime-io/src/lib.rs @@ -14,7 +14,9 @@ // You should have received a copy of the GNU General Public License // along with Substrate. If not, see . +// tag::description[] //! This is part of the Substrate runtime. +// end::description[] #![cfg_attr(not(feature = "std"), no_std)] #![cfg_attr(not(feature = "std"), feature(lang_items))] diff --git a/substrate/runtime-sandbox/README.adoc b/substrate/runtime-sandbox/README.adoc new file mode 100644 index 0000000000000..61a203708c811 --- /dev/null +++ b/substrate/runtime-sandbox/README.adoc @@ -0,0 +1,13 @@ + += Runtime Sandbox + +.Summary +[source, toml] +---- +include::Cargo.toml[lines=2..5] +---- + +.Description +---- +include::src/lib.rs[tag=description] +---- diff --git a/substrate/runtime-sandbox/src/lib.rs b/substrate/runtime-sandbox/src/lib.rs index e0e6cdf09fe26..16066af160f15 100755 --- a/substrate/runtime-sandbox/src/lib.rs +++ b/substrate/runtime-sandbox/src/lib.rs @@ -14,6 +14,7 @@ // You should have received a copy of the GNU General Public License // along with Substrate. If not, see . +// tag::description[] //! This crate provides means of instantiation and execution of wasm modules. //! //! It works even when the user of this library is itself executes @@ -34,6 +35,7 @@ //! - implementing smart-contract runtimes which uses wasm for contract code //! - executing wasm substrate runtime inside of a wasm parachain //! - etc +// end::description[] #![warn(missing_docs)] #![cfg_attr(not(feature = "std"), no_std)] diff --git a/substrate/runtime-std/README.adoc b/substrate/runtime-std/README.adoc new file mode 100644 index 0000000000000..36ea8d99c2262 --- /dev/null +++ b/substrate/runtime-std/README.adoc @@ -0,0 +1,14 @@ + += Runtime std + +.Summary +[source, toml] +---- +include::Cargo.toml[lines=2..5] +---- + +.Description +---- +include::src/lib.rs[tag=description] +---- + diff --git a/substrate/runtime-std/src/lib.rs b/substrate/runtime-std/src/lib.rs index aabcd0122f779..d0fddddd298af 100644 --- a/substrate/runtime-std/src/lib.rs +++ b/substrate/runtime-std/src/lib.rs @@ -14,8 +14,10 @@ // You should have received a copy of the GNU General Public License // along with Substrate. If not, see . +// tag::description[] //! Lowest-abstraction level for the Substrate runtime: just exports useful primitives from std //! or core/alloc to be used with any code that depends on the runtime. +// end::description[] #![cfg_attr(not(feature = "std"), no_std)] #![cfg_attr(not(feature = "std"), feature(panic_handler))] diff --git a/substrate/runtime-support/README.adoc b/substrate/runtime-support/README.adoc new file mode 100644 index 0000000000000..699235e5ae650 --- /dev/null +++ b/substrate/runtime-support/README.adoc @@ -0,0 +1,14 @@ + += Runtime Support + +.Summary +[source, toml] +---- +include::Cargo.toml[lines=2..5] +---- + +.Description +---- +include::src/lib.rs[tag=description] +---- + diff --git a/substrate/runtime-support/src/lib.rs b/substrate/runtime-support/src/lib.rs index 21823b383fa32..6e109ca2edc29 100644 --- a/substrate/runtime-support/src/lib.rs +++ b/substrate/runtime-support/src/lib.rs @@ -14,7 +14,9 @@ // You should have received a copy of the GNU General Public License // along with Substrate. If not, see . +// tag::description[] //! Support code for the runtime. +// end::description[] #![cfg_attr(not(feature = "std"), no_std)] @@ -169,7 +171,7 @@ macro_rules! impl_outer_origin { impl_outer_origin! { $(#[$attr])* pub enum $name for $trait where system = system { - $( $module ),* + $( $module ),* } } } diff --git a/substrate/runtime/README.adoc b/substrate/runtime/README.adoc new file mode 100644 index 0000000000000..616c12568a076 --- /dev/null +++ b/substrate/runtime/README.adoc @@ -0,0 +1,6 @@ + += Runtime + +Set of libs for the substrate runtime. + +TODO: Add READMEs to packages. diff --git a/substrate/runtime/primitives/src/generic/mod.rs b/substrate/runtime/primitives/src/generic/mod.rs index fd56cb4015421..f7cf9ad8f48d5 100644 --- a/substrate/runtime/primitives/src/generic/mod.rs +++ b/substrate/runtime/primitives/src/generic/mod.rs @@ -14,7 +14,9 @@ // You should have received a copy of the GNU General Public License // along with Substrate. If not, see . +// tag::description[] //! Generic implementations of Extrinsic/Header/Block. +// end::description[] mod unchecked_extrinsic; mod checked_extrinsic; diff --git a/substrate/serializer/README.adoc b/substrate/serializer/README.adoc new file mode 100644 index 0000000000000..7b780bae43677 --- /dev/null +++ b/substrate/serializer/README.adoc @@ -0,0 +1,14 @@ + += Serializer + +.Summary +[source, toml] +---- +include::Cargo.toml[lines=2..5] +---- + +.Description +---- +include::src/lib.rs[tag=description] +---- + diff --git a/substrate/serializer/src/lib.rs b/substrate/serializer/src/lib.rs index 74cf155ce77e8..48afc57497354 100644 --- a/substrate/serializer/src/lib.rs +++ b/substrate/serializer/src/lib.rs @@ -14,10 +14,12 @@ // You should have received a copy of the GNU General Public License // along with Substrate. If not, see . +// tag::description[] //! Substrate customizable serde serializer. //! //! The idea is that we can later change the implementation //! to something more compact, but for now we're using JSON. +// end::description[] #![warn(missing_docs)] diff --git a/substrate/service/README.adoc b/substrate/service/README.adoc new file mode 100644 index 0000000000000..4d74c098b2e17 --- /dev/null +++ b/substrate/service/README.adoc @@ -0,0 +1,14 @@ + += Service + +.Summary +[source, toml] +---- +include::Cargo.toml[lines=2..5] +---- + +.Description +---- +include::src/lib.rs[tag=description] +---- + diff --git a/substrate/service/src/lib.rs b/substrate/service/src/lib.rs index e8319d8fd88ce..40afc4f6daf9f 100644 --- a/substrate/service/src/lib.rs +++ b/substrate/service/src/lib.rs @@ -14,8 +14,10 @@ // You should have received a copy of the GNU General Public License // along with Substrate. If not, see . +// tag::description[] //! Substrate service. Starts a thread that spins the network, the client and the extrinsic pool. //! Manages communication between them. +// end::description[] #![warn(unused_extern_crates)] @@ -79,7 +81,7 @@ pub use components::{ServiceFactory, FullBackend, FullExecutor, LightBackend, LightExecutor, Components, PoolApi, ComponentClient, ComponentBlock, FullClient, LightClient, FullComponents, LightComponents, CodeExecutor, NetworkService, FactoryChainSpec, FactoryBlock, - FactoryFullConfiguration, RuntimeGenesis, FactoryGenesis, + FactoryFullConfiguration, RuntimeGenesis, FactoryGenesis, ComponentExHash, ComponentExtrinsic, }; @@ -423,4 +425,4 @@ impl network::TransactionPool, ComponentBlock< fn on_broadcasted(&self, propagations: HashMap, Vec>) { self.pool.on_broadcasted(propagations) } -} \ No newline at end of file +} diff --git a/substrate/state-db/README.adoc b/substrate/state-db/README.adoc new file mode 100644 index 0000000000000..f9934ed8d9ac6 --- /dev/null +++ b/substrate/state-db/README.adoc @@ -0,0 +1,13 @@ + += State DB + +.Summary +[source, toml] +---- +include::Cargo.toml[lines=2..5] +---- + +.Description +---- +include::src/lib.rs[tag=description] +---- diff --git a/substrate/state-db/src/lib.rs b/substrate/state-db/src/lib.rs index 7cb8fcca2da6d..7e7dd3369c918 100644 --- a/substrate/state-db/src/lib.rs +++ b/substrate/state-db/src/lib.rs @@ -14,6 +14,7 @@ // You should have received a copy of the GNU General Public License // along with Substrate. If not, see . +// tag::description[] //! State database maintenance. Handles finalization and pruning in the database. The input to //! this module is a `ChangeSet` which is basically a list of key-value pairs (trie nodes) that //! were added or deleted during block execution. @@ -29,6 +30,7 @@ //! See `RefWindow` for pruning algorithm details. `StateDb` prunes on each finalization until pruning //! constraints are satisfied. //! +// end::description[] #[macro_use] extern crate log; #[macro_use] extern crate substrate_codec_derive; diff --git a/substrate/state-machine/README.adoc b/substrate/state-machine/README.adoc new file mode 100644 index 0000000000000..aad08bed989db --- /dev/null +++ b/substrate/state-machine/README.adoc @@ -0,0 +1,13 @@ + += State Machine + +.Summary +[source, toml] +---- +include::Cargo.toml[lines=2..5] +---- + +.Description +---- +include::src/lib.rs[tag=description] +---- diff --git a/substrate/state-machine/src/lib.rs b/substrate/state-machine/src/lib.rs index 4b4bc4fc4c687..fc3f52c5dcb5c 100644 --- a/substrate/state-machine/src/lib.rs +++ b/substrate/state-machine/src/lib.rs @@ -14,7 +14,9 @@ // You should have received a copy of the GNU General Public License // along with Substrate. If not, see . +// tag::description[] //! Substrate state machine implementation. +// end::description[] #![warn(missing_docs)] diff --git a/substrate/telemetry/README.adoc b/substrate/telemetry/README.adoc new file mode 100644 index 0000000000000..9759c5bc50bdd --- /dev/null +++ b/substrate/telemetry/README.adoc @@ -0,0 +1,13 @@ + += Telemetry + +.Summary +[source, toml] +---- +include::Cargo.toml[lines=2..5] +---- + +.Description +---- +include::src/lib.rs[tag=description] +---- diff --git a/substrate/telemetry/src/lib.rs b/substrate/telemetry/src/lib.rs index 1054b7b397d4e..21e8685b36031 100644 --- a/substrate/telemetry/src/lib.rs +++ b/substrate/telemetry/src/lib.rs @@ -14,12 +14,14 @@ // You should have received a copy of the GNU General Public License // along with Substrate. If not, see . +// tag::description[] //! Telemetry utils. -//! +//! //! `telemetry` macro be used from whereever in the Substrate codebase //! in order to send real-time logging information to the telemetry //! server (if there is one). We use the async drain adapter of `slog` //! so that the logging thread doesn't get held up at all. +// end::description[] extern crate parking_lot; extern crate websocket as ws; diff --git a/substrate/test-client/README.adoc b/substrate/test-client/README.adoc new file mode 100644 index 0000000000000..e56c4c7f66e7c --- /dev/null +++ b/substrate/test-client/README.adoc @@ -0,0 +1,13 @@ + += Test client + +.Summary +[source, toml] +---- +include::Cargo.toml[lines=2..5] +---- + +.Description +---- +include::src/lib.rs[tag=description] +---- diff --git a/substrate/test-client/src/lib.rs b/substrate/test-client/src/lib.rs index 334ec4a0f56e2..4de63d46a28a0 100644 --- a/substrate/test-client/src/lib.rs +++ b/substrate/test-client/src/lib.rs @@ -14,7 +14,9 @@ // You should have received a copy of the GNU General Public License // along with Substrate. If not, see . +// tag::description[] //! Client testing utilities. +// end::description[] #![warn(missing_docs)] diff --git a/substrate/test-runtime/README.adoc b/substrate/test-runtime/README.adoc new file mode 100644 index 0000000000000..15b3c4c4ac327 --- /dev/null +++ b/substrate/test-runtime/README.adoc @@ -0,0 +1,13 @@ + += Test runtime + +.Summary +[source, toml] +---- +include::Cargo.toml[lines=2..5] +---- + +.Description +---- +include::src/lib.rs[tag=description] +---- diff --git a/substrate/test-runtime/src/lib.rs b/substrate/test-runtime/src/lib.rs index 0bf753a9443a4..a6225213b7bb4 100644 --- a/substrate/test-runtime/src/lib.rs +++ b/substrate/test-runtime/src/lib.rs @@ -14,7 +14,9 @@ // You should have received a copy of the GNU General Public License // along with Substrate. If not, see . +// tag::description[] //! The Substrate runtime. This can be compiled with #[no_std], ready for Wasm. +// end::description[] #![cfg_attr(not(feature = "std"), no_std)]