From a6596582bf13f826fb15d9ad460c858f70c4f928 Mon Sep 17 00:00:00 2001
From: Luke Schoen <ltfschoen@users.noreply.github.com>
Date: Thu, 25 Oct 2018 18:34:49 +0200
Subject: [PATCH] docs: Relates to #578 Minor fixes to documentation section in
 Readme (#992)

* docs: Fix syntax for module comment. Rename to substrate Core

* docs: Reorder package layers in order of level of abstraction

* docs: Make text more concise

* docs: Add SRML abbreviation
---
 substrate/README.adoc | 35 ++++++++++++++++++-----------------
 1 file changed, 18 insertions(+), 17 deletions(-)

diff --git a/substrate/README.adoc b/substrate/README.adoc
index ad17955d0b4..fe964993171 100644
--- a/substrate/README.adoc
+++ b/substrate/README.adoc
@@ -238,30 +238,31 @@ cargo doc --package <spec> --open
 
 Replacing `<spec>` with one of the following (i.e. `cargo doc --package node-cli --open`):
 
-* Node
+* Substrate Core
 [source, shell]
-node-cli, node-consensus, node-executor, node-network, node-primitives, node-runtime, node-service
+substrate, substrate-bft, substrate-cli, substrate-client, substrate-client-db,
+substrate-executor, substrate-finality-grandpa, substrate-keyring, substrate-keystore,
+substrate-metadata, substrate-misbehavior-check, substrate-network,
+substrate-network-libp2p, substrate-primitives, substrate-rpc, substrate-rpc-servers,
+substrate-serializer, substrate-service, substrate-service-test, substrate-state-db,
+substrate-state-machine, substrate-telemetry, substrate-test-client,
+substrate-test-runtime, substrate-transaction-graph, substrate-transaction-pool,
+substrate-trie
 * Substrate Runtime
 [source, shell]
 sr-api, sr-io, sr-primitives, sr-sandbox, sr-std, sr-version
-* Substrate Runtime Module Library
+* Substrate Runtime Module Library (SRML)
 [source, shell]
 srml-balances, srml-consensus, srml-contract, srml-council, srml-democracy, srml-example,
 srml-executive, srml-session, srml-staking, srml-support, srml-system, srml-timestamp,
 srml-treasury
+* Node
+[source, shell]
+node-cli, node-consensus, node-executor, node-network, node-primitives, node-runtime, node-service
 * Subkey
 [source, shell]
 subkey
-* Substrate
-[source, shell]
-substrate, substrate-bft, substrate-cli, substrate-client, substrate-client-db,
-substrate-executor, substrate-finality-grandpa, substrate-keyring, substrate-keystore,
-substrate-metadata, substrate-misbehavior-check, substrate-network,
-substrate-network-libp2p, substrate-primitives, substrate-rpc, substrate-rpc-servers,
-substrate-serializer, substrate-service, substrate-service-test, substrate-state-db,
-substrate-state-machine, substrate-telemetry, substrate-test-client,
-substrate-test-runtime, substrate-transaction-graph, substrate-transaction-pool,
-substrate-trie
+
 
 === Contributing to documentation for Substrate packages
 
@@ -293,9 +294,9 @@ Example (generic):
 ** Documentation comments must use annotations with a triple slash `///`
 ** Modules are documented using `//!` 
 ```
-/// Summary (of module)
-///
-/// Description (of module)
+//! Summary (of module)
+//!
+//! Description (of module)
 ```
 * Special section header is indicated with a hash `#`. 
 ** `Panics` section requires an explanation if the function triggers a panic
@@ -311,7 +312,7 @@ after the triple graves, alternative annotations include the `ignore`, `text`, `
 or errors `#![deny(missing_docs)]`
 * Hide documentation for items with `#[doc(hidden)]`
 
-=== Contributing to documentation (as tests, for extended examples, and for macros) for Substrate packages
+=== Contributing to documentation (tests, extended examples, macros) for Substrate packages
 
 The code block annotations in the `# Example` section may be used as https://doc.rust-lang.org/1.9.0/book/documentation.html#documentation-as-tests[documentation as tests and for extended examples].
 
-- 
GitLab