fix some warnings

developer-hub/src/lib.rs

@@ -31,7 +31,9 @@
 //!
 //! ### Checklist
 //!
-//! TODO
+//! - [ ] Always make sure all downstream types and items are improved.
+//! - [ ] Make sure you read all relevant documents, build on top of. Imagine the process of posting
+//!   something new in SE.
 //!
 //! ### Note on `crates.io` and Publishing
 //!
@@ -102,8 +104,8 @@
 //!
 //! For more details about documenting guidelines, see:
 //! <https://github.com/paritytech/polkadot-sdk/master/docs/DOCUMENTATION_GUIDELINES.md>
-#![deny(rustdoc::broken_intra_doc_links)]
-#![deny(rustdoc::private_intra_doc_links)]
+#![warn(rustdoc::broken_intra_doc_links)]
+#![warn(rustdoc::private_intra_doc_links)]
 
 /// An introduction to the Polkadot SDK. Read this module to learn about the structure of the SDK,
 /// the tools that are provided as a part of it, and to gain a high level understanding of each.

developer-hub/src/polkadot_sdk/mod.rs

@@ -15,12 +15,12 @@
 //! [![Runtime](https://img.shields.io/badge/fellowship-runtimes-e6007a?logo=polkadot)](https://github.com/polkadot-fellows/runtimes)
 //! [![Manifesto](https://img.shields.io/badge/fellowship-manifesto-e6007a?logo=polkadot)](https://github.com/polkadot-fellows/manifesto)
 //!
-//!
 //! ## Getting Started
 //!
 //! The primary way to get started with the Polkadot SDK is to start writing a Substrate-based
 //! runtime using FRAME. See:
 //!
+//! 0. [`polkadot`], to understand what is Polkadot as a development platform.
 //! 1. [`substrate`], for an overview of what Substrate is.
 //! 2. Jump right into [`frame`] to learn about how to write a FRAME-based blockchain runtime.
 //! 3. Continue with the [`developer_hub`'s "getting started"](crate#getting-started).
@@ -119,3 +119,6 @@ pub mod smart_contracts;
 pub mod substrate;
 /// Index of all the templates that can act as an initial scaffold for a new project.
 pub mod templates;
+
+/// Learn about XCM, the de-facto communication language between different consensus systems.
+pub mod xcm;

developer-hub/src/polkadot_sdk/polkadot.rs

@@ -4,10 +4,55 @@
 //!
 //! ## Getting Involved
 //!
-//! [![PolkadotForum](https://img.shields.io/badge/Polkadot_Forum-e6007a?logo=polkadot)](https://forum.polkadot.network/)
-//! - RFCs TODO
-//! - Polkadot Fellowship TODO
-//! - Polkadot Specs
-//! - Polkadot Implementor's guide
+//! - [Polkadot Forum](https://forum.polkadot.network/)
+//! - Polkadot Fellowship
+//! 	- [Runtimes](https://github.com/polkadot-fellows/runtimes)
+//! 	- [RFCs](https://github.com/polkadot-fellows/rfcs)
+//! - [Polkadot Specs](spec.polkadot.network)
+//! - [The Polkadot Parachain Host Implementers' Guide](https://paritytech.github.io/polkadot-sdk/book/)
+//! - [Whitepaper](https://www.polkadot.network/whitepaper/)
 //!
-//! ## What is Polkadot
+//! ## Platform
+//!
+//! ### Polkadot 1.x
+//!
+//! The original vision of Polkadot (i.e. **Polkadot 1**) revolves around the following arguments:
+//!
+//! * Future is multi-chain, because we need different chains with different specialization to
+//!   achieve widespread goals.
+//! * In other words, no single chain is good enough to achieve this.
+//! * A multi-chain future will inadvertently suffer from fragmentation of economic security.
+//!   * This stake fragmentation will make communication over consensus system with varying security
+//!     levels inherently unsafe.
+//!
+//! Polkadot's answer to the above is:
+//!
+//! * Shared Security: The idea of shared economic security sits at the core of Polkadot. Polkadot
+//!   enables different blockchains (ie. "*Parachains*") to pool their economic security from
+//!   Polkadot (ie. "*Relay Chain*").
+//! * A framework to build blockchains: In order to materialize the multi-chain future, an easy
+//!   blockchain framework must exist. This is [`crate::polkadot_sdk::substrate`],
+//!   [`crate::polkadot_sdk::frame_runtime`] and [`crate::polkadot_sdk::cumulus`].
+//! * A communication language between blockchains: In order for these blockchains to communicate,
+//!   they need a shared language. [`crate::polkadot_sdk::xcm`] is one such language.
+//!
+//! > Note that the interoperability promised by Polkadot is unparalleled in that any two parachains
+//! > connected to Polkadot have the same security and can have much higher guarantees about the
+//! > security of the recipient of any message.
+//!
+//! Polkadot delivers the above vision, alongside a flexible means for parachains to schedule
+//! themselves with the Relay Chain. To achieve this, Polkadot has been developed with an
+//! architecture similar to that of a computer. Polkadot Relay Chain has a number of "cores". Each
+//! is (in simple terms) is capable of progressing 1 parachain a a time. For example, a parachain
+//! can schedule itself for on a single core for 5 blocks.
+//!
+//! Within the scope of Polkadot 1.x, two main scheduling ways has been considered:
+//!
+//! * Long term Parachains, obtained through locking a sum of DOT in an auction system.
+//! * on-demand Parachains, purchased through paying DOT to the relay-chain whenever needed.
+//!
+//! This scheduling system, and its evolution is the segway into Polkadot 2.x
+//!
+//! ### Polkadot 2.x
+//!
+//! <TODO>

developer-hub/src/polkadot_sdk/templates.rs

@@ -4,3 +4,13 @@
 //! - classic [cumulus-parachain-template](https://github.com/substrate-developer-hub/substrate-parachain-template)
 //! - [`extended-parachain-template`](https://github.com/paritytech/extended-parachain-template)
 //! - [`frontier-parachain-template`](https://github.com/paritytech/frontier-parachain-template)
+
+// NOTE: a super important detail that I am looking forward to here is
+// <https://github.com/paritytech/polkadot-sdk/issues/62#issuecomment-1691523754> and
+// <https://github.com/paritytech/polkadot-sdk/issues/5>. Meaning that I would not spend time on
+// teaching someone too much detail about the ugly thing we call "node" nowadays. In the future, I
+// am sure we will either have a better "node-builder" code that can actually be tested, or an
+// "omni-node" that can run (almost) any wasm file. We should already build tutorials in this
+// direction IMO. This also affects all the templates. If we have a good neat runtime file, which we
+// are moving toward, and a good node-builder, we don't need all of these damn templates. These
+// templates are only there because the boilerplate is super horrible atm.

developer-hub/src/polkadot_sdk/xcm.rs

@@ -0,0 +1 @@
+//! # XCM

developer-hub/src/reference_docs/mod.rs

@@ -56,3 +56,7 @@ pub mod frame_composite_enums;
 /// Learn about how to make a pallet/runtime that is fee-less and instead uses another mechanism to
 /// control usage and sybil attacks.
 pub mod fee_less_runtime;
+
+/// Learn about metadata, the main means through which an upgrade-able runtime communicate its
+/// properties to the outside world.
+pub mod metadata;

docs/mermaid/IA.mmd

@@ -9,5 +9,6 @@ flowchart
     polkadot_sdk --> frame
     polkadot_sdk --> cumulus
     polkadot_sdk --> polkadot
+    polkadot_sdk --> xcm
 
 

substrate/frame/support/src/lib.rs

@@ -47,7 +47,9 @@ pub mod __private {
 	pub use sp_core::{OpaqueMetadata, Void};
 	pub use sp_core_hashing_proc_macro;
 	pub use sp_inherents;
-	pub use sp_io::{self, storage::root as storage_root, TestExternalities};
+	#[cfg(feature = "std")]
+	pub use sp_io::TestExternalities;
+	pub use sp_io::{self, storage::root as storage_root};
 	pub use sp_metadata_ir as metadata_ir;
 	#[cfg(feature = "std")]
 	pub use sp_runtime::{bounded_btree_map, bounded_vec};