Fix doc warnings and setup doc lint

Concordium · Sep 26, 2023 · 519dbc5 · 519dbc5
1 parent 3bdeef7
commit 519dbc5
Show file tree

Hide file tree

Showing 8 changed files with 82 additions and 26 deletions.
diff --git a/.github/workflows/linter-testing-lib.yaml b/.github/workflows/linter-testing-lib.yaml
@@ -2,6 +2,7 @@ name: "Testing library: Format, lint, build, and test"
 
 # This job runs:
 # - rustfmt
+# - rustdoc
 # - clippy linting
 # - tests
 # for the smart contract testing library.
@@ -18,10 +19,10 @@ on:
       - synchronize
       - ready_for_review
     paths:
-      - 'contract-testing/**/*.rs'
-      - 'contract-testing/**/*.toml'
-      - 'rustfmt.toml'
-      - 'concordium-rust-sdk'
+      - "contract-testing/**/*.rs"
+      - "contract-testing/**/*.toml"
+      - "rustfmt.toml"
+      - "concordium-rust-sdk"
 
   workflow_dispatch: # allows manual trigger
 
@@ -38,7 +39,7 @@ jobs:
     strategy:
       matrix:
         build-dir:
-          - 'contract-testing'
+          - "contract-testing"
     steps:
       - name: Checkout
         uses: actions/checkout@v3
@@ -54,6 +55,29 @@ jobs:
         run: |
           cargo fmt -- --color=always --check
 
+  "lint_doc":
+    name: ${{ matrix.build-dir }} lint:doc
+    # Don't run on draft pull requests
+    if: ${{ !github.event.pull_request.draft }}
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        build-dir:
+          - "contract-testing"
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+      - name: Install Rust
+        uses: actions-rs/toolchain@v1
+        with:
+          profile: minimal
+          toolchain: ${{ env.RUST_CLIPPY }}
+          override: true
+      - name: Format
+        working-directory: ${{ matrix.build-dir }}
+        run: |
+          RUSTDOCFLAGS="-D warnings" cargo doc --no-deps --all-features
+
   "lint_clippy":
     name: ${{ matrix.build-dir }} lint:clippy
     # Don't run on draft pull requests
@@ -62,7 +86,7 @@ jobs:
     strategy:
       matrix:
         build-dir:
-          - 'contract-testing'
+          - "contract-testing"
     steps:
       - name: Checkout
         uses: actions/checkout@v3
@@ -88,7 +112,7 @@ jobs:
     strategy:
       matrix:
         build-dir:
-          - 'contract-testing'
+          - "contract-testing"
     steps:
       - name: Checkout
         uses: actions/checkout@v3

diff --git a/.github/workflows/linter.yml b/.github/workflows/linter.yml
@@ -14,7 +14,6 @@ env:
   RUST_FMT: nightly-2023-04-01
   RUST_VERSION: "1.66"
 
-
 jobs:
   rustfmt:
     name: Format
@@ -69,6 +68,35 @@ jobs:
           command: fmt
           args: --manifest-path=${{ matrix.crates }} -- --check
 
+  rustdoc:
+    name: Lint docs
+    # Don't run on draft pull requests
+    if: ${{ !github.event.pull_request.draft }}
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        crates:
+          - concordium-std
+          - concordium-cis2
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v2
+        with:
+          submodules: recursive
+
+      - name: Install Rust
+        uses: actions-rs/toolchain@v1
+        with:
+          profile: minimal
+          toolchain: ${{ env.RUST_VERSION }}
+          override: true
+
+      - name: Run cargo doc
+        working-directory: ${{ matrix.crates }}
+        run: |
+          RUSTDOCFLAGS="-D warnings" cargo doc --no-deps --all-features
+
   # All templates are generated with the `cargo-generate` command and it is checked that the 'cargo test' command
   # can be executed without errors on the generated smart contracts.
   cargo-generate-templates:
@@ -468,7 +496,6 @@ jobs:
           command: clippy
           args: --manifest-path ${{ matrix.lib-crates }} --target=${{ matrix.target }} --features=${{ matrix.features }} -- -D warnings
 
-
   clippy-wasm32-only:
     name: Clippy Wasm32
     runs-on: ubuntu-latest
@@ -750,7 +777,6 @@ jobs:
           # Run all tests, including doc tests.
           args: --manifest-path ${{ matrix.lib-crates }} --target=${{ matrix.target }} --features=${{ matrix.features }}
 
-
   test-examples:
     name: Test examples
     runs-on: ubuntu-latest

diff --git a/concordium-cis2/Cargo.toml b/concordium-cis2/Cargo.toml
@@ -36,4 +36,4 @@ opt-level = "s"
 targets = ["wasm32-unknown-unknown"]
 # Default features to build documentation for.
 features = ["std", "u256_amount"]
-rustc-args = ["--cfg", "docsrs"]
+rustc-args = ["--cfg", "docsrs"]
diff --git a/concordium-cis2/src/lib.rs b/concordium-cis2/src/lib.rs
@@ -24,12 +24,13 @@
 //!     // ...
 //!     Ok(A::accept())
 //! }
+//! ```
 //!
 //! # Features
 //!
 //! This crate has features `std` and `u256_amount`. The former one is default.
-//! When `u256_amount` feature is enabled the type [`TokenAmountU256`] is defined
-//! and implements the [`IsTokenAmount`] interface.
+//! When `u256_amount` feature is enabled the type [`TokenAmountU256`] is
+//! defined and implements the [`IsTokenAmount`] interface.
 #![cfg_attr(not(feature = "std"), no_std)]
 
 mod cis2_client;
@@ -69,13 +70,14 @@ pub const UPDATE_OPERATOR_EVENT_TAG: u8 = u8::MAX - 3;
 pub const TOKEN_METADATA_EVENT_TAG: u8 = u8::MAX - 4;
 
 /// Trait for marking types as CIS2 token IDs.
-/// For a type to be a valid CIS2 token ID it must implement SchemaType and
-/// Serialize, such that the first byte indicates how many bytes is used to
-/// represent the token ID, followed by this many bytes for the token ID.
+/// For a type to be a valid CIS2 token ID it must implement
+/// `SchemaType` and `Serialize`, such that the first
+/// byte indicates how many bytes is used to represent the token ID, followed by
+/// this many bytes for the token ID.
 ///
 /// Note: The reason for introducing such a trait instead of representing every
-/// token ID using Vec<u8> is to allow smart contracts to use specialized token
-/// ID implementations avoiding allocations.
+/// token ID using `Vec<u8>` is to allow smart contracts to use specialized
+/// token ID implementations avoiding allocations.
 pub trait IsTokenId: Serialize + schema::SchemaType {}
 
 /// Trait for marking types as CIS2 token amounts.
@@ -84,7 +86,7 @@ pub trait IsTokenId: Serialize + schema::SchemaType {}
 /// 37 bytes.
 ///
 /// Note: The reason for introducing such a trait instead of representing every
-/// token amount using [u8; 37] is to allow smart contracts to use specialized
+/// token amount using `[u8; 37]` is to allow smart contracts to use specialized
 /// token amount implementations avoiding doing arithmetics of large integers.
 pub trait IsTokenAmount: Serialize + schema::SchemaType {}
 

diff --git a/concordium-std/src/traits.rs b/concordium-std/src/traits.rs
@@ -373,8 +373,9 @@ pub trait HasHost<State>: Sized {
 
     /// Get the current public balance of an account. Here public means
     /// unencrypted or unshielded. See
-    /// [`AccountBalance`](crate::types::AccountBalance) for more.
-    /// This query will fail if the provided address does not exist on chain.
+    /// [`AccountBalance`](concordium_contracts_common::AccountBalance) for
+    /// more. This query will fail if the provided address does not exist on
+    /// chain.
     ///
     /// Any amount received by transfers during the transaction
     /// until the point of querying are reflected in this balance.

diff --git a/concordium-std/src/types.rs b/concordium-std/src/types.rs
@@ -692,7 +692,8 @@ pub type QueryAccountBalanceResult = Result<AccountBalance, QueryAccountBalanceE
 pub type QueryContractBalanceResult = Result<Amount, QueryContractBalanceError>;
 
 /// A wrapper around [`Result`] that fixes the error variant to
-/// [`QueryAccountPublicKeysError`] and result to [`AccountPublicKeys`].
+/// [`QueryAccountPublicKeysError`] and result to
+/// [`AccountPublicKeys`](crate::AccountPublicKeys).
 pub type QueryAccountPublicKeysResult =
     Result<crate::AccountPublicKeys, QueryAccountPublicKeysError>;
 

diff --git a/contract-testing/src/impls.rs b/contract-testing/src/impls.rs
@@ -1324,7 +1324,7 @@ impl Chain {
     /// Add an external account from a connected external node.
     ///
     /// If the account exists on the external node at the time of the
-    /// `external_query_block`, then an [`ExernalAccountAddress`] is returned.
+    /// `external_query_block`, then an [`ExternalAccountAddress`] is returned.
     /// The address can be used with [`Chain::contract_invoke_external`].
     /// Otherwise, an error is returned.
     ///
@@ -1359,7 +1359,7 @@ impl Chain {
     /// Add an external contract from a connected external node.
     ///
     /// If the contract exists on the external node at the time of the
-    /// `external_query_block`, then an [`ExernalContractAddress`] is returned.
+    /// `external_query_block`, then an [`ExternalContractAddress`] is returned.
     /// The address can be used with [`Chain::contract_invoke_external`].
     /// Otherwise, an error is returned.
     ///

diff --git a/contract-testing/src/types.rs b/contract-testing/src/types.rs
@@ -986,8 +986,10 @@ impl ExternalAddress {
 
 /// Data needed to invoke an external smart contract instance.
 ///
-/// This is nearly identical to [`UpdateContractPayload`] except that it uses an
-/// [`ExternalContractAddress`] instead of an [`ContractAddress`].
+/// This is nearly identical to
+/// [`UpdateContractPayload`](concordium_base::transactions::UpdateContractPayload)
+/// except that it uses an [`ExternalContractAddress`] instead of an
+/// [`ContractAddress`].
 #[derive(Debug, Clone)]
 pub struct InvokeExternalContractPayload {
     /// Send the given amount of CCD together with the message to the