ci: add a cargo doc job (#1269)

* ci: add a `cargo doc` job * doc: fix doc generation warnings + couple nomicon.io broken links --------- Co-authored-by: dj8yf0μl <[email protected]>
near · Dec 3, 2024 · 5a4c595 · 5a4c595
1 parent da3f1f4
commit 5a4c595
Show file tree

Hide file tree

Showing 12 changed files with 45 additions and 19 deletions.
diff --git a/.github/workflows/coverage.yml b/.github/workflows/coverage.yml
@@ -16,7 +16,7 @@ jobs:
         platform: [macos-latest]
         toolchain: [stable]
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
       - name: Install Homebrew
         run: |
           /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

diff --git a/.github/workflows/release-plz.yml b/.github/workflows/release-plz.yml
@@ -15,7 +15,7 @@ jobs:
     if: github.ref == 'refs/heads/master'
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
         with:
           fetch-depth: 0
           token: ${{ secrets.CUSTOM_GITHUB_TOKEN }}

diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
@@ -24,7 +24,7 @@ jobs:
             rs: stable
         features: ['', '--features unstable,legacy,__abi-generate']
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
       - name: "${{ matrix.platform.rs }} with rustfmt, and wasm32"
         uses: actions-rs/toolchain@v1
         with:
@@ -45,7 +45,7 @@ jobs:
     name: Clippy and fmt
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
       - name: Install stable toolchain
         uses: actions-rs/toolchain@v1
         with:
@@ -61,7 +61,7 @@ jobs:
     name: Compilation tests
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
       - name: Install stable toolchain
         uses: actions-rs/toolchain@v1
         with:
@@ -75,7 +75,7 @@ jobs:
     name: Windows
     runs-on: windows-latest
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
       - name: "Setup Windows toolchain"
         uses: actions-rs/toolchain@v1
         with:
@@ -93,7 +93,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout Sources
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
       - name: Install Toolchain
         uses: actions-rs/toolchain@v1
         with:
@@ -105,3 +105,25 @@ jobs:
         run: cargo install cargo-audit
       - name: Run Audit
         run: cargo audit
+  # there're sometimes warnings, which signal, that the generated doc
+  # won't look as expected, when rendered, and sometimes errors, which will prevent doc from being
+  # generated at release time altogether.
+  cargo-doc:
+    runs-on: ubuntu-20.04
+
+    steps:
+    - uses: actions/checkout@v4
+    - name: Install Toolchain
+      uses: actions-rs/toolchain@v1
+      with:
+        profile: minimal
+        toolchain: stable
+        default: true
+    - name: run cargo doc
+      env:
+        RUSTDOCFLAGS: -D warnings
+      run: |
+        cargo doc -p near-sdk --features unstable,legacy,unit-testing,__macro-docs
+        cargo doc -p near-sdk-macros
+        cargo doc -p near-contract-standards --no-deps
+        cargo doc -p near-sys
diff --git a/.github/workflows/test_examples.yml b/.github/workflows/test_examples.yml
@@ -25,7 +25,7 @@ jobs:
           factory-contract
         ]
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
       - name: "${{ matrix.toolchain }} with rustfmt, and wasm32"
         uses: actions-rs/toolchain@v1
         with:

diff --git a/.github/workflows/test_examples_small.yml b/.github/workflows/test_examples_small.yml
@@ -22,7 +22,7 @@ jobs:
           test-contract,
         ]
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
       - name: "${{ matrix.toolchain }} with rustfmt, clippy, and wasm32"
         uses: actions-rs/toolchain@v1
         with:

diff --git a/.github/workflows/typo.yml b/.github/workflows/typo.yml
@@ -7,7 +7,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
     - name: Checkout Actions Repository
-      uses: actions/checkout@v2
+      uses: actions/checkout@v4
     - name: Check spelling of the entire repository
       uses: crate-ci/[email protected]
 
diff --git a/near-contract-standards/src/fungible_token/mod.rs b/near-contract-standards/src/fungible_token/mod.rs
@@ -1,3 +1,5 @@
+//! Fungible tokens as described in [by the spec](https://nomicon.io/Standards/Tokens/FungibleToken).
+//!
 //! This module represents a Fungible Token standard.
 //!
 //! # Examples

diff --git a/near-contract-standards/src/lib.rs b/near-contract-standards/src/lib.rs
@@ -2,12 +2,14 @@
 #![allow(clippy::missing_const_for_fn, clippy::redundant_pub_crate)]
 #![allow(clippy::needless_lifetimes)]
 
-/// Fungible tokens as described in [by the spec](https://nomicon.io/Standards/FungibleToken/README.html).
 pub mod fungible_token;
-/// Non-fungible tokens as described in [by the spec](https://nomicon.io/Standards/NonFungibleToken/README.html).
+
+/// Non-fungible tokens as described in [by the spec](https://nomicon.io/Standards/Tokens/NonFungibleToken).
 pub mod non_fungible_token;
+
 /// Storage management deals with handling [state storage](https://docs.near.org/docs/concepts/storage-staking) on NEAR. This follows the [storage management standard](https://nomicon.io/Standards/StorageManagement.html).
 pub mod storage_management;
+
 /// This upgrade standard is a use case where a staging area exists for a WASM
 /// blob, allowing it to be stored for a period of time before deployed.
 #[deprecated(

diff --git a/near-sdk/src/store/mod.rs b/near-sdk/src/store/mod.rs
@@ -20,8 +20,8 @@
 //! If your collection has up to 100 entries, it's acceptable to use the native collection, as it might be simpler
 //! since you don't have to manage prefixes as we do with near collections.
 //! However, if your collection has 1,000 or more entries, it's better to use a near collection. The investigation
-//! mentioned above shows that running the contains method on a native HashSet<i32> consumes 41% more gas
-//! compared to a near IterableSet<i32>.
+//! mentioned above shows that running the contains method on a native [`std::collections::HashSet<i32>`] consumes 41% more gas
+//! compared to a near [`crate::store::IterableSet<i32>`].
 //!
 //! It's also a bad practice to have a native collection properties as a top level properties of your contract.
 //! The contract will load all the properties before the contract method invocation. That means that all your native
@@ -52,7 +52,7 @@
 //! - [`UnorderedMap`]: Storage version of [`std::collections::HashMap`]. No ordering
 //!   guarantees.
 //!
-//! - [`TreeMap`](TreeMap) (`unstable`): Storage version of [`std::collections::BTreeMap`]. Ordered by key,
+//! - [`TreeMap`] (`unstable`): Storage version of [`std::collections::BTreeMap`]. Ordered by key,
 //!   which comes at the cost of more expensive lookups and iteration.
 //!
 //! Sets:

diff --git a/near-sdk/src/test_utils/context.rs b/near-sdk/src/test_utils/context.rs
@@ -65,7 +65,7 @@ pub struct VMContext {
     pub random_seed: [u8; 32],
     /// If Some, it means that execution is made in a view mode and defines its configuration.
     /// View mode means that only read-only operations are allowed.
-    /// See <https://nomicon.io/Proposals/0018-view-change-method.html> for more details.
+    /// See <https://nomicon.io/Proposals/view-change-method> for more details.
     pub view_config: Option<ViewConfig>,
     /// How many `DataReceipt`'s should receive this execution result. This should be empty if
     /// this function call is a part of a batch and it is not the last action.

diff --git a/near-sdk/src/test_utils/mod.rs b/near-sdk/src/test_utils/mod.rs
@@ -19,7 +19,7 @@ pub use context::{accounts, testing_env_with_promise_results, VMContextBuilder};
 ///   about the VM to configure parameters not directly related to the transaction being executed.
 /// - `fee_config`(optional): [`RuntimeFeesConfig`] which configures the
 ///   fees for execution and storage of transactions.
-/// - `validators`(optional): a [`HashMap`]<[`AccountId`], [`Balance`]> mocking the
+/// - `validators`(optional): a [`HashMap`]<[`AccountId`], [`NearToken`]> mocking the
 ///   current validators of the blockchain.
 /// - `promise_results`(optional): a [`Vec`] of [`PromiseResult`] which mocks the results
 ///   of callback calls during the execution.
@@ -57,7 +57,7 @@ pub use context::{accounts, testing_env_with_promise_results, VMContextBuilder};
 /// [`vm::Config`]: near_parameters::vm::Config
 /// [`RuntimeFeesConfig`]: near_parameters::RuntimeFeesConfig
 /// [`AccountId`]: crate::AccountId
-/// [`Balance`]: crate::Balance
+/// [`NearToken`]: crate::NearToken
 /// [`PromiseResult`]: crate::PromiseResult
 /// [`HashMap`]: std::collections::HashMap
 #[macro_export]

diff --git a/near-sdk/src/test_utils/test_env.rs b/near-sdk/src/test_utils/test_env.rs
@@ -32,7 +32,7 @@ pub fn setup() {
 }
 
 /// free == effectively unlimited gas
-/// Sets up the blockchain interface with a [`VMConfig`] which sets the gas costs to zero.
+/// Sets up the blockchain interface with a [`near_parameters::vm::Config`] which sets the gas costs to zero.
 pub fn setup_free() {
     let mut config = test_vm_config();
     config.make_free();