fix docs

.github/workflows/rust-checks.yaml

@@ -16,6 +16,20 @@ env:
   TOOLCHAIN_LINT: nightly-2023-11-13
 
 jobs:
+  check-doc:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install Rust ${{ env.TOOLCHAIN_LINT }}
+        uses: dtolnay/rust-toolchain@stable
+        with:
+          targets: wasm32-unknown-unknown
+      - uses: Swatinem/rust-cache@v2
+        with:
+          key: check-doc-v0
+      - name: cargo doc
+        run: RUST_FLAGS="-D warnings" cargo doc
+
   lint:
     runs-on: ubuntu-latest
     steps:

cli/main.rs

@@ -149,18 +149,10 @@
 //! arbitrary encoded data (usually some pre-upgrade state) which will be passed to
 //! [`OnRuntimeUpgrade::pre_upgrade`] after upgrading and used for post checking.
 //!
-//! ### Guarding migrations and [`VersionedRuntimeUpgrade`]
+//! ### [`VersionedMigration`]
 //!
-//! Always make sure that any migration code is guarded either by `StorageVersion`, or by some
-//! custom storage item, so that it is NEVER executed twice, even if the code lives in two
-//! consecutive runtimes.
-//!
-//! TODO: Briefly explain [`VersionedRuntimeUpgrade`] and link out to its docs.
-//!
-//! #### Examples
-//!
-//! TODO: Provide end-to-end examples of writing a runtime upgrade, and testing it with the CLI. One
-//! example with [`VersionedRuntimeUpgrade`], one without.
+//! It is strongly suggested to use [`VersionedMigration`] when writing custom migrations for
+//! pallets.
 //!
 //! ### State Consistency
 //!
@@ -286,7 +278,7 @@
 //!     --try-state rr-3
 //! ```
 //!
-//! [`VersionedRuntimeUpgrade`]: https://paritytech.github.io/substrate/master/frame_support/migrations/struct.VersionedRuntimeUpgrade.html
+//! [`VersionedMigration`]: https://paritytech.github.io/polkadot-sdk/master/frame_support/migrations/struct.VersionedMigration.html
 //! [`OnRuntimeUpgrade`]: https://paritytech.github.io/substrate/master/frame_support/traits/trait.OnRuntimeUpgrade.html
 //! [`OnRuntimeUpgrade::pre_upgrade`]: https://paritytech.github.io/substrate/master/frame_support/traits/trait.OnRuntimeUpgrade.html#method.pre_upgrade
 //! [`OnRuntimeUpgrade::post_upgrade`]: https://paritytech.github.io/substrate/master/frame_support/traits/trait.OnRuntimeUpgrade.html#method.post_upgrade

core/src/state.rs

@@ -140,7 +140,7 @@ pub enum State {
     Live(LiveState),
 }
 
-/// Options for [`to_ext`]
+/// Options for [`State::to_ext`]
 ///
 /// Whether to check that the runtime was compiled with try-runtime feature
 #[derive(PartialEq, PartialOrd)]
@@ -150,7 +150,7 @@ pub enum TryRuntimeFeatureCheck {
     /// Don't check if the runtime was compiled with try-runtime feature
     Skip,
 }
-/// Options for [`to_ext`]
+/// Options for [`State::to_ext`]
 ///
 /// Whether to check if the new runtime `spec_version` is greater than the previous runtime
 /// `spec_version`
@@ -169,7 +169,7 @@ impl State {
     ///
     /// This will override the code as it sees fit based on [`Runtime`]. It will also check the
     /// spec-version and name.
-    pub(crate) async fn to_ext<Block: BlockT + DeserializeOwned, HostFns: HostFunctions>(
+    pub async fn to_ext<Block: BlockT + DeserializeOwned, HostFns: HostFunctions>(
         &self,
         shared: &SharedParams,
         executor: &WasmExecutor<HostFns>,