From 7aaf4dccc2ca4dd2e9308137c5ad95fa286d22c5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Michael=20M=C3=BCller?= Date: Tue, 2 Feb 2021 15:28:04 +0100 Subject: [PATCH] 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 563bfeb3cd53bdb0e358d53e9c42853c860d1485. * Prettify paragraph * Remove unnecessary imports * Revert "Remove unnecessary imports" This reverts commit 0520713397442ffbad15927e295da71ab880c9ce. * 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 Co-authored-by: Hero Bird --- .gitlab-ci.yml | 14 +++++++ crates/env/src/backend.rs | 40 +++++++++---------- crates/env/src/engine/off_chain/db/block.rs | 6 +-- crates/env/src/engine/off_chain/test_api.rs | 2 +- .../codegen/src/generator/cross_calling.rs | 2 +- .../storage/src/collections/bitstash/mod.rs | 4 +- .../storage/src/collections/smallvec/mod.rs | 5 ++- crates/storage/src/collections/stash/mod.rs | 3 +- crates/storage/src/collections/vec/mod.rs | 3 +- crates/storage/src/lazy/entry.rs | 20 +++++----- crates/storage/src/lazy/lazy_hmap.rs | 3 +- crates/storage/src/lazy/mod.rs | 2 +- examples/dns/lib.rs | 4 +- examples/rand-extension/lib.rs | 1 + examples/rand-extension/runtime/README.md | 3 +- 15 files changed, 66 insertions(+), 46 deletions(-) diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml index 137cdaa97f7..5fae601efa1 100644 --- a/.gitlab-ci.yml +++ b/.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: diff --git a/crates/env/src/backend.rs b/crates/env/src/backend.rs index 48ac4b17484..d8d5ae8eb6f 100644 --- a/crates/env/src/backend.rs +++ b/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(&mut self) -> Result; /// 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(&mut self) -> Result; /// 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(&mut self, gas: u64) -> Result; /// 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(&mut self) -> Result; /// 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(&mut self) -> Result; /// 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(&mut self) -> Result; /// Returns the balance of the executed contract. /// /// # Note /// - /// For more details visit: [`ink_env::balance`] + /// For more details visit: [`balance`][`crate::balance`] fn balance(&mut self) -> Result; /// 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(&mut self) -> Result; /// 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(&mut self) -> Result; /// 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(&mut self) -> Result; /// 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(&mut self) -> Result; /// 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(&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(&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( &mut self, call_data: &CallParams, @@ -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( &mut self, call_data: &CallParams>, @@ -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( &mut self, params: &CreateParams, @@ -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( &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(&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(&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(&mut self, subject: &[u8]) -> Result where T: Environment; diff --git a/crates/env/src/engine/off_chain/db/block.rs b/crates/env/src/engine/off_chain/db/block.rs index 3393f2c348f..f6eb2d5d173 100644 --- a/crates/env/src/engine/off_chain/db/block.rs +++ b/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(&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). /// diff --git a/crates/env/src/engine/off_chain/test_api.rs b/crates/env/src/engine/off_chain/test_api.rs index e60b74b1033..e9b97e4cea8 100644 --- a/crates/env/src/engine/off_chain/test_api.rs +++ b/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(entropy: T::Hash) -> Result<()> where T: Environment, diff --git a/crates/lang/codegen/src/generator/cross_calling.rs b/crates/lang/codegen/src/generator/cross_calling.rs index 104303d405f..5de7c021747 100644 --- a/crates/lang/codegen/src/generator/cross_calling.rs +++ b/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, diff --git a/crates/storage/src/collections/bitstash/mod.rs b/crates/storage/src/collections/bitstash/mod.rs index 9cee9e0e079..570c26b8425 100644 --- a/crates/storage/src/collections/bitstash/mod.rs +++ b/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 { diff --git a/crates/storage/src/collections/smallvec/mod.rs b/crates/storage/src/collections/smallvec/mod.rs index 737c6dd1182..e8078767850 100644 --- a/crates/storage/src/collections/smallvec/mod.rs +++ b/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 diff --git a/crates/storage/src/collections/stash/mod.rs b/crates/storage/src/collections/stash/mod.rs index 40c4f1e31f3..56a9aa67427 100644 --- a/crates/storage/src/collections/stash/mod.rs +++ b/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 diff --git a/crates/storage/src/collections/vec/mod.rs b/crates/storage/src/collections/vec/mod.rs index 7d8bc5e2563..827bd5bee9f 100644 --- a/crates/storage/src/collections/vec/mod.rs +++ b/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 diff --git a/crates/storage/src/lazy/entry.rs b/crates/storage/src/lazy/entry.rs index 3c73db03ee4..ed3cbfd92e5 100644 --- a/crates/storage/src/lazy/entry.rs +++ b/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::(&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::(&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::(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::>(self.value(), &root_key); } diff --git a/crates/storage/src/lazy/lazy_hmap.rs b/crates/storage/src/lazy/lazy_hmap.rs index 994692b9e3a..7efea7c99cf 100644 --- a/crates/storage/src/lazy/lazy_hmap.rs +++ b/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 { diff --git a/crates/storage/src/lazy/mod.rs b/crates/storage/src/lazy/mod.rs index 7c0818f0def..30bfb90136a 100644 --- a/crates/storage/src/lazy/mod.rs +++ b/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. //! diff --git a/examples/dns/lib.rs b/examples/dns/lib.rs index acca1006507..986a992eea7 100644 --- a/examples/dns/lib.rs +++ b/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 /// diff --git a/examples/rand-extension/lib.rs b/examples/rand-extension/lib.rs index ecb22a0875f..cb808caa47f 100755 --- a/examples/rand-extension/lib.rs +++ b/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; diff --git a/examples/rand-extension/runtime/README.md b/examples/rand-extension/runtime/README.md index 0e006c94200..22f0f70c174 100644 --- a/examples/rand-extension/runtime/README.md +++ b/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` \ No newline at end of file +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`.