Fix broken intra-doc links + add CI stage to test example docs (#606)

* Fix broken intra-doc links

* Fix doc link

* Add CI stage to test example docs

* Revert me: Provoke doc failures in example

* Remove intra-crate link to non-dependency

* Remove `--all-features`

* Revert "Revert me: Provoke doc failures in example"

This reverts commit 563bfeb.

* Prettify paragraph

* Remove unnecessary imports

* Revert "Remove unnecessary imports"

This reverts commit 0520713.

* Remove unnecessary imports

* Remove `cfg(doc)` path resolution for doc comments

* Improve language and formatting

* Upgrade `scale` and `scale-info` for `rand-extension`

* Make http link work

* Remove `crate::` prefix from doc links

* Apply suggestions from code review

Co-authored-by: Hero Bird <[email protected]>

Co-authored-by: Hero Bird <[email protected]>

Author: Michael Müller

.gitlab-ci.yml

@@ -264,6 +264,20 @@ examples-contract-build:
         popd;
       done
 
+examples-docs:
+    stage:                           examples
+    <<:                              *docker-env
+    variables:
+        RUSTDOCFLAGS: -Dwarnings
+    script:
+        # `--document-private-items` needs to be in here because currently our contract macro
+        # puts the contract functions in a private module.
+        # Once https://github.com/paritytech/ink/issues/336 has been implemented we can get rid
+        # of this flag.
+        - for example in examples/*/; do
+            cargo doc --manifest-path ${example}/Cargo.toml --document-private-items --verbose --no-deps;
+          done
+
 #### stage:                        publish
 
 publish-docs:

crates/env/src/backend.rs

@@ -169,84 +169,84 @@ pub trait TypedEnvBackend: EnvBackend {
     ///
     /// # Note
     ///
-    /// For more details visit: [`ink_env::caller`]
+    /// For more details visit: [`caller`][`crate::caller`]
     fn caller<T: Environment>(&mut self) -> Result<T::AccountId>;
 
     /// Returns the transferred balance for the contract execution.
     ///
     /// # Note
     ///
-    /// For more details visit: [`ink_env::transferred_balance`]
+    /// For more details visit: [`transferred_balance`][`crate::transferred_balance`]
     fn transferred_balance<T: Environment>(&mut self) -> Result<T::Balance>;
 
     /// Returns the price for the specified amount of gas.
     ///
     /// # Note
     ///
-    /// For more details visit: [`ink_env::gas_price`]
+    /// For more details visit: [`weight_to_fee`][`crate::weight_to_fee`]
     fn weight_to_fee<T: Environment>(&mut self, gas: u64) -> Result<T::Balance>;
 
     /// Returns the amount of gas left for the contract execution.
     ///
     /// # Note
     ///
-    /// For more details visit: [`ink_env::gas_left`]
+    /// For more details visit: [`gas_left`][`crate::gas_left`]
     fn gas_left<T: Environment>(&mut self) -> Result<T::Balance>;
 
     /// Returns the timestamp of the current block.
     ///
     /// # Note
     ///
-    /// For more details visit: [`ink_env::block_timestamp`]
+    /// For more details visit: [`block_timestamp`][`crate::block_timestamp`]
     fn block_timestamp<T: Environment>(&mut self) -> Result<T::Timestamp>;
 
     /// Returns the address of the executed contract.
     ///
     /// # Note
     ///
-    /// For more details visit: [`ink_env::account_id`]
+    /// For more details visit: [`account_id`][`crate::account_id`]
     fn account_id<T: Environment>(&mut self) -> Result<T::AccountId>;
 
     /// Returns the balance of the executed contract.
     ///
     /// # Note
     ///
-    /// For more details visit: [`ink_env::balance`]
+    /// For more details visit: [`balance`][`crate::balance`]
     fn balance<T: Environment>(&mut self) -> Result<T::Balance>;
 
     /// Returns the current rent allowance for the executed contract.
     ///
     /// # Note
     ///
-    /// For more details visit: [`ink_env::rent_allowance`]
+    /// For more details visit: [`rent_allowance`][`crate::rent_allowance`]
     fn rent_allowance<T: Environment>(&mut self) -> Result<T::Balance>;
 
     /// Returns the current block number.
     ///
     /// # Note
     ///
-    /// For more details visit: [`ink_env::block_number`]
+    /// For more details visit: [`block_number`][`crate::block_number`]
     fn block_number<T: Environment>(&mut self) -> Result<T::BlockNumber>;
 
     /// Returns the minimum balance that is required for creating an account.
     ///
     /// # Note
     ///
-    /// For more details visit: [`ink_env::minimum_balance`]
+    /// For more details visit: [`minimum_balance`][`crate::minimum_balance`]
     fn minimum_balance<T: Environment>(&mut self) -> Result<T::Balance>;
 
     /// Returns the tombstone deposit of the contract chain.
     ///
     /// # Note
     ///
-    /// For more details visit: [`ink_env::tombstone_deposit`]
+    /// For more details visit: [`tombstone_deposit`][`crate::tombstone_deposit`]
     fn tombstone_deposit<T: Environment>(&mut self) -> Result<T::Balance>;
 
     /// Emits an event with the given event data.
     ///
     /// # Note
     ///
-    /// For more details visit: [`ink_env::emit_event`]
+    /// For more details visit: [`emit_event`][`crate::emit_event`]
     fn emit_event<T, Event>(&mut self, event: Event)
     where
         T: Environment,
@@ -256,7 +256,7 @@ pub trait TypedEnvBackend: EnvBackend {
     ///
     /// # Note
     ///
-    /// For more details visit: [`ink_env::set_rent_allowance`]
+    /// For more details visit: [`set_rent_allowance`][`crate::set_rent_allowance`]
     fn set_rent_allowance<T>(&mut self, new_value: T::Balance)
     where
         T: Environment;
@@ -265,7 +265,7 @@ pub trait TypedEnvBackend: EnvBackend {
     ///
     /// # Note
     ///
-    /// For more details visit: [`ink_env::invoke_contract`]
+    /// For more details visit: [`invoke_contract`][`crate::invoke_contract`]
     fn invoke_contract<T, Args>(
         &mut self,
         call_data: &CallParams<T, Args, ()>,
@@ -278,7 +278,7 @@ pub trait TypedEnvBackend: EnvBackend {
     ///
     /// # Note
     ///
-    /// For more details visit: [`ink_env::eval_contract`]
+    /// For more details visit: [`eval_contract`][`crate::eval_contract`]
     fn eval_contract<T, Args, R>(
         &mut self,
         call_data: &CallParams<T, Args, ReturnType<R>>,
@@ -292,7 +292,7 @@ pub trait TypedEnvBackend: EnvBackend {
     ///
     /// # Note
     ///
-    /// For more details visit: [`ink_env::instantiate_contract`]
+    /// For more details visit: [`instantiate_contract`][`crate::instantiate_contract`]
     fn instantiate_contract<T, Args, Salt, C>(
         &mut self,
         params: &CreateParams<T, Args, Salt, C>,
@@ -306,7 +306,7 @@ pub trait TypedEnvBackend: EnvBackend {
     ///
     /// # Note
     ///
-    /// For more details visit: [`ink_env::restore_contract`]
+    /// For more details visit: [`restore_contract`][`crate::restore_contract`]
     fn restore_contract<T>(
         &mut self,
         account_id: T::AccountId,
@@ -320,7 +320,7 @@ pub trait TypedEnvBackend: EnvBackend {
     ///
     /// # Note
     ///
-    /// For more details visit: [`ink_env::terminate_contract`]
+    /// For more details visit: [`terminate_contract`][`crate::terminate_contract`]
     fn terminate_contract<T>(&mut self, beneficiary: T::AccountId) -> !
     where
         T: Environment;
@@ -329,7 +329,7 @@ pub trait TypedEnvBackend: EnvBackend {
     ///
     /// # Note
     ///
-    /// For more details visit: [`ink_env::transfer`]
+    /// For more details visit: [`transfer`][`crate::transfer`]
     fn transfer<T>(&mut self, destination: T::AccountId, value: T::Balance) -> Result<()>
     where
         T: Environment;
@@ -338,7 +338,7 @@ pub trait TypedEnvBackend: EnvBackend {
     ///
     /// # Note
     ///
-    /// For more details visit: [`ink_env::random`]
+    /// For more details visit: [`random`][`crate::random`]
     fn random<T>(&mut self, subject: &[u8]) -> Result<T::Hash>
     where
         T: Environment;

crates/env/src/engine/off_chain/db/block.rs

@@ -34,7 +34,7 @@ pub struct Block {
     /// # Note
     ///
     /// - Can optionally be set for more control via
-    ///   [`crate::set_block_randomization_hash`].
+    ///   [`test::set_block_entropy`][`crate::test::set_block_entropy`].
     entropy: OffHash,
 }
 
@@ -75,7 +75,7 @@ impl Block {
     ///
     /// # Note
     ///
-    /// This is mainly used to control what [`crate::random`] returns
+    /// This is mainly used to control what [`random`][`crate::random`] returns
     /// in the off-chain environment.
     pub fn set_entropy<T>(&mut self, new_entropy: T::Hash) -> Result<()>
     where
@@ -89,7 +89,7 @@ impl Block {
     /// # Note
     ///
     /// - This is the off-chain environment implementation of
-    /// [`crate::random`]. It provides the same behaviour in that it
+    /// [`random`][`crate::random`]. It provides the same behaviour in that it
     /// will likely yield the same hash for the same subjects within the same
     /// block (or execution context).
     ///

crates/env/src/engine/off_chain/test_api.rs

@@ -194,7 +194,7 @@ where
 ///
 /// # Note
 ///
-/// This allows to control what [`crate::random`] returns.
+/// This allows to control what [`random`][`crate::random`] returns.
 pub fn set_block_entropy<T>(entropy: T::Hash) -> Result<()>
 where
     T: Environment,

crates/lang/codegen/src/generator/cross_calling.rs

@@ -140,7 +140,7 @@ impl CrossCalling<'_> {
         }
     }
 
-    /// Builds up the [`ink_env::call::ArgumentList`] type structure for the given types.
+    /// Builds up the `ink_env::call::utils::ArgumentList` type structure for the given types.
     fn generate_arg_list<'a, Args>(args: Args) -> TokenStream2
     where
         Args: IntoIterator<Item = &'a syn::Type>,

crates/storage/src/collections/bitstash/mod.rs

@@ -71,7 +71,9 @@ impl BitStash {
     /// in the `free` list.
     ///
     /// Returns the bit position of the first bit in the 256-bit chunk and not
-    /// the chunk position since that's what [`Bitvec::get_chunk`] expects.
+    /// the chunk position since that's what
+    /// [`Bitvec::get_chunk`][`crate::collections::Bitvec::get_chunk`]
+    /// expects.
     ///
     /// Also directly increases the count of the first found free bit chunk.
     fn position_first_zero(&mut self) -> Option<u64> {

crates/storage/src/collections/smallvec/mod.rs

@@ -14,7 +14,7 @@
 
 //! A small storage vector that allows to store a limited amount of elements.
 //!
-//! Prefer using [`SmallVec`] over [`crate::Vec`] if you know up front
+//! Prefer using [`SmallVec`] over [`Vec`][`crate::Vec`] if you know up front
 //! the maximum amount of unique elements that have to be stored in the vector
 //! at the same time, given the number is fairly low: e.g. not exceeding several
 //! hundreds of elements.
@@ -89,7 +89,8 @@ where
     /// the contents of its associated storage region.
     ///
     /// This API is used for the `Drop` implementation of [`Vec`] as well as
-    /// for the [`SpreadLayout::clear_spread`] trait implementation.
+    /// for the [`SpreadLayout::clear_spread`][`crate::traits::SpreadLayout::clear_spread`]
+    /// trait implementation.
     fn clear_cells(&self) {
         if self.elems.key().is_none() {
             // We won't clear any storage if we are in lazy state since there

crates/storage/src/collections/stash/mod.rs

@@ -266,7 +266,8 @@ where
     /// the contents of its associated storage region.
     ///
     /// This API is used for the `Drop` implementation of [`Vec`] as well as
-    /// for the [`SpreadLayout::clear_spread`] trait implementation.
+    /// for the [`SpreadLayout::clear_spread`][`crate::traits::SpreadLayout::clear_spread`]
+    /// trait implementation.
     fn clear_cells(&self) {
         if self.entries.key().is_none() {
             // We won't clear any storage if we are in lazy state since there

crates/storage/src/collections/vec/mod.rs

@@ -109,7 +109,8 @@ where
     /// the contents of its associated storage region.
     ///
     /// This API is used for the `Drop` implementation of [`Vec`] as well as
-    /// for the [`SpreadLayout::clear_spread`] trait implementation.
+    /// for the [`SpreadLayout::clear_spread`][`crate::traits::SpreadLayout::clear_spread`]
+    /// trait implementation.
     fn clear_cells(&self) {
         if self.elems.key().is_none() {
             // We won't clear any storage if we are in lazy state since there

crates/storage/src/lazy/entry.rs

@@ -12,11 +12,6 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-#[cfg(doc)]
-use crate::lazy::{
-    LazyArray,
-    LazyIndexMap,
-};
 use crate::traits::{
     clear_packed_root,
     clear_spread_root_opt,
@@ -187,7 +182,7 @@ where
     /// # Note
     ///
     /// Mainly used by lazy storage abstractions that only allow operating on
-    /// packed storage entities such as [`LazyCell`].
+    /// packed storage entities such as [`LazyCell`][`crate::lazy::LazyCell`].
     pub fn pull_spread_root(root_key: &Key) -> Self {
         Self::new(pull_spread_root_opt::<T>(&root_key), EntryState::Preserved)
     }
@@ -197,7 +192,7 @@ where
     /// # Note
     ///
     /// Mainly used by lazy storage abstractions that only allow operating on
-    /// packed storage entities such as [`LazyCell`].
+    /// packed storage entities such as [`LazyCell`][`crate::lazy::LazyCell`].
     pub fn push_spread_root(&self, root_key: &Key) {
         let old_state = self.replace_state(EntryState::Preserved);
         if old_state.is_mutated() {
@@ -210,7 +205,7 @@ where
     /// # Note
     ///
     /// Mainly used by lazy storage abstractions that only allow operating on
-    /// packed storage entities such as [`LazyCell`].
+    /// packed storage entities such as [`LazyCell`][`crate::lazy::LazyCell`].
     pub fn clear_spread_root(&self, root_key: &Key) {
         clear_spread_root_opt::<T, _>(&root_key, || self.value().into());
     }
@@ -225,7 +220,8 @@ where
     /// # Note
     ///
     /// Mainly used by lazy storage abstractions that only allow operating on
-    /// packed storage entities such as [`LazyIndexMap`] or [`LazyArray`].
+    /// packed storage entities such as [`LazyIndexMap`][`crate::lazy::LazyIndexMap`] or
+    /// [`LazyArray`][`crate::lazy::LazyArray`].
     pub fn pull_packed_root(root_key: &Key) -> Self {
         Self::new(pull_packed_root_opt::<T>(root_key), EntryState::Preserved)
     }
@@ -235,7 +231,8 @@ where
     /// # Note
     ///
     /// Mainly used by lazy storage abstractions that only allow operating on
-    /// packed storage entities such as [`LazyIndexMap`] or [`LazyArray`].
+    /// packed storage entities such as [`LazyIndexMap`][`crate::lazy::LazyIndexMap`]
+    /// or [`LazyArray`][`crate::lazy::LazyArray`].
     pub fn push_packed_root(&self, root_key: &Key) {
         let old_state = self.replace_state(EntryState::Preserved);
         if old_state.is_mutated() {
@@ -248,7 +245,8 @@ where
     /// # Note
     ///
     /// Mainly used by lazy storage abstractions that only allow operating on
-    /// packed storage entities such as [`LazyIndexMap`] or [`LazyArray`].
+    /// packed storage entities such as [`LazyIndexMap`][`crate::lazy::LazyIndexMap`]
+    /// or [`LazyArray`][`crate::lazy::LazyArray`].
     pub fn clear_packed_root(&self, root_key: &Key) {
         clear_packed_root::<Option<T>>(self.value(), &root_key);
     }

crates/storage/src/lazy/lazy_hmap.rs

@@ -361,7 +361,8 @@ where
     ///
     /// This constructor is private and should never need to be called from
     /// outside this module. It is used to construct a lazy index map from a
-    /// key that is only useful upon a contract call. Use [`LazyIndexMap::new`]
+    /// key that is only useful upon a contract call. Use
+    /// [`LazyIndexMap::new`][`crate::lazy::LazyIndexMap::new`]
     /// for construction during contract initialization.
     fn lazy(key: Key) -> Self {
         Self {

crates/storage/src/lazy/mod.rs

@@ -17,7 +17,7 @@
 //!
 //! Users should generally avoid using these collections directly in their
 //! contracts and should instead adhere to the high-level collections found
-//! in [`crate::collections`].
+//! in [`collections`][`crate::collections`].
 //! The low-level collections are mainly used as building blocks for internals
 //! of other higher-level storage collections.
 //!

examples/dns/lib.rs

@@ -58,8 +58,8 @@ mod dns {
         new_owner: AccountId,
     }
 
-    /// Domain name service contract inspired by ChainX's [blog post]
-    /// (https://medium.com/@chainx_org/secure-and-decentralized-polkadot-domain-name-system-e06c35c2a48d).
+    /// Domain name service contract inspired by ChainX's
+    /// [blog post](https://medium.com/@chainx_org/secure-and-decentralized-polkadot-domain-name-system-e06c35c2a48d).
     ///
     /// # Note
     ///

examples/rand-extension/lib.rs

@@ -11,6 +11,7 @@
 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 // See the License for the specific language governing permissions and
 // limitations under the License.
+
 #![cfg_attr(not(feature = "std"), no_std)]
 
 use ink_env::Environment;

examples/rand-extension/runtime/README.md

@@ -1,3 +1,4 @@
 # Chain-side Extension
 
-use this as an implement of trait `ChainExtension` in substrate and use it as the associated type ChainExtension of trait `pallet_contracts::Config`
+Use this as an implementation of the trait `ChainExtension` in Substrate
+and use it as the associated type `ChainExtension` of the trait `pallet_contracts::Config`.