From 5a4c595125364ffe8d7866aa0418a3c92b1c3a6a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?dj8yf0=CE=BCl?= <26653921+dj8yfo@users.noreply.github.com> Date: Tue, 3 Dec 2024 12:45:01 +0200 Subject: [PATCH] ci: add a `cargo doc` job (#1269) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * ci: add a `cargo doc` job * doc: fix doc generation warnings + couple nomicon.io broken links --------- Co-authored-by: dj8yf0μl --- .github/workflows/coverage.yml | 2 +- .github/workflows/release-plz.yml | 2 +- .github/workflows/test.yml | 32 ++++++++++++++++--- .github/workflows/test_examples.yml | 2 +- .github/workflows/test_examples_small.yml | 2 +- .github/workflows/typo.yml | 2 +- .../src/fungible_token/mod.rs | 2 ++ near-contract-standards/src/lib.rs | 6 ++-- near-sdk/src/store/mod.rs | 6 ++-- near-sdk/src/test_utils/context.rs | 2 +- near-sdk/src/test_utils/mod.rs | 4 +-- near-sdk/src/test_utils/test_env.rs | 2 +- 12 files changed, 45 insertions(+), 19 deletions(-) diff --git a/.github/workflows/coverage.yml b/.github/workflows/coverage.yml index ecfd50dc7..489343d1d 100644 --- 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 index 22141ea19..21c7e358e 100644 --- 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 index a13726c93..3ea29e1ac 100644 --- 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 index d8790f7c8..278b8a904 100644 --- 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 index fde99636e..9c3f41e9a 100644 --- 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 index 021c55fd4..6bbce31c0 100644 --- 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/typos@v1.11.1 diff --git a/near-contract-standards/src/fungible_token/mod.rs b/near-contract-standards/src/fungible_token/mod.rs index eb0698fca..1210748ab 100644 --- 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 index 3a3b86d73..edd387d12 100644 --- 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 index ec724474a..ad1f3c5f7 100644 --- 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 consumes 41% more gas -//! compared to a near IterableSet. +//! mentioned above shows that running the contains method on a native [`std::collections::HashSet`] consumes 41% more gas +//! compared to a near [`crate::store::IterableSet`]. //! //! 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 index 07766d6f4..45823aa69 100644 --- 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 for more details. + /// See for more details. pub view_config: Option, /// 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 index 02f2fea2b..b305c0c98 100644 --- 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 index 15b789fcd..670b40029 100644 --- 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();