Fix cargo doc (#1788)

* Fix cargo doc errors * Fix cargo doc * Add CI for cargo doc * Fix cargo doc * Fix Markdown link * Fix review feedback
informalsystems · Feb 17, 2022 · f1a4481 · f1a4481
1 parent 202ae4e
commit f1a4481
Show file tree

Hide file tree

Showing 20 changed files with 64 additions and 34 deletions.
diff --git a/.github/workflows/cargo-doc.yaml b/.github/workflows/cargo-doc.yaml
@@ -0,0 +1,27 @@
+name: Publish Cargo Doc
+
+on:
+  push:
+    branches:
+      - master
+  pull_request: {}
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+
+      - uses: actions-rs/toolchain@v1
+        with:
+          toolchain: stable
+
+      - run: cargo doc
+
+      - name: Deploy
+        if: ${{ github.ref == 'ref/head/master' }}
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          deploy_key: ${{ secrets.IBC_RS_DOC_PRIVATE_KEY }}
+          external_repository: informalsystems/ibc-rs-doc
+          publish_dir: ./target/doc
diff --git a/docs/architecture/adr-007-error.md b/docs/architecture/adr-007-error.md
@@ -7,7 +7,7 @@
 ## Context
 
 This document describes the reason behind the switch from using
-[`anomaly`](https://docs.rs/anomaly) for error handling to
+`anomaly` for error handling to
 the [`flex-error`](https://docs.rs/flex-error/) crate that is developed in-house.
 
 ## Decision

diff --git a/modules/src/applications/mod.rs b/modules/src/applications/mod.rs
@@ -9,7 +9,7 @@ pub mod ics27_interchain_accounts {
     /// of the full port identifier, which has a
     /// complex structure.
     ///
-    /// https://github.com/cosmos/ibc/tree/master/spec/app/ics-027-interchain-accounts#registering--controlling-flows
+    /// <https://github.com/cosmos/ibc/tree/master/spec/app/ics-027-interchain-accounts#registering--controlling-flows>
     pub const PORT_ID_PREFIX: &str = "ics27-1.";
 
     /// ICS27 application current version.

diff --git a/modules/src/clients/ics07_tendermint/client_state.rs b/modules/src/clients/ics07_tendermint/client_state.rs
@@ -150,8 +150,7 @@ impl ClientState {
         elapsed > self.trusting_period
     }
 
-    /// Helper method to produce a
-    /// [`tendermint_light_client::light_client::Options`] struct for use in
+    /// Helper method to produce a [`Options`] struct for use in
     /// Tendermint-specific light client verification.
     pub fn as_light_client_options(&self) -> Result<Options, Error> {
         Ok(Options {

diff --git a/modules/src/core/ics23_commitment/merkle.rs b/modules/src/core/ics23_commitment/merkle.rs
@@ -35,7 +35,7 @@ pub struct MerkleProof {
 
 /// Convert to ics23::CommitmentProof
 /// The encoding and decoding shouldn't fail since ics23::CommitmentProof and ibc_proto::ics23::CommitmentProof should be the same
-/// Ref. https://github.com/informalsystems/ibc-rs/issues/853
+/// Ref. <https://github.com/informalsystems/ibc-rs/issues/853>
 impl From<RawMerkleProof> for MerkleProof {
     fn from(proof: RawMerkleProof) -> Self {
         let proofs: Vec<CommitmentProof> = proof

diff --git a/modules/src/lib.rs b/modules/src/lib.rs
@@ -6,7 +6,6 @@
 #![allow(clippy::large_enum_variant)]
 #![deny(
     warnings,
-    // missing_docs,
     trivial_casts,
     trivial_numeric_casts,
     unused_import_braces,

diff --git a/modules/src/timestamp.rs b/modules/src/timestamp.rs
@@ -134,7 +134,7 @@ impl Timestamp {
         self.time.map(Into::into)
     }
 
-    /// Convert a `Timestamp` to an optional [`Tendermint::Time`]
+    /// Convert a `Timestamp` to an optional [`tendermint::Time`]
     pub fn into_tm_time(self) -> Option<Time> {
         self.time
     }

diff --git a/relayer/src/chain/handle/requests.rs b/relayer/src/chain/handle/requests.rs
@@ -1,7 +1,8 @@
 //! Domain-type definitions for requests that a
-//! [`ChainHandle`] can accept. These types trickle
-//! down to the [`ChainEndpoint`] trait. Any chain
-//! that the ibc-relayer library supports will have
+//! [`ChainHandle`](crate::chain::handle::ChainHandle) can accept.
+//! These types trickle down to the
+//! [`ChainEndpoint`](crate::chain::ChainEndpoint) trait.
+//! Any chain that the ibc-relayer library supports will have
 //! to implement these requests.
 
 use ibc::core::{

diff --git a/relayer/src/chain/tx.rs b/relayer/src/chain/tx.rs
@@ -4,7 +4,8 @@ use prost_types::Any;
 /// (`Vec<Any>`), which has an associated tracking
 /// number.
 ///
-/// A [`TrackedMsgs`] correlates with a [`TrackedEvents`]
+/// A [`TrackedMsgs`] correlates with a
+/// [`TrackedEvents`](crate::link::operational_data::TrackedEvents)
 /// by sharing the same `tracking_id`.
 #[derive(Debug, Clone)]
 pub struct TrackedMsgs {

diff --git a/relayer/src/config/reload.rs b/relayer/src/config/reload.rs
@@ -43,7 +43,7 @@ impl ConfigReload {
     /// the path to the configuration file to reload,
     /// the current configuration and a channel through which
     /// to send the computed [`ConfigUpdate`]s to the
-    /// [`crate::supervisor::Supervisor`].
+    /// supervisor.
     pub fn new(
         path: impl Into<PathBuf>,
         current: Arc<RwLock<Config>>,
@@ -60,7 +60,7 @@ impl ConfigReload {
     /// This method will read and parse the configuration from the
     /// file, then perform a diff between the current configuration
     /// and the newly parsed one, and finally send the computed
-    /// [`ConfigUpdate`]s to the [`crate::supervisor::Supervisor`].
+    /// [`ConfigUpdate`]s to the supervisor.
     ///
     /// See also: [`ConfigReload::update_config`]
     pub fn reload(&self) -> Result<bool, Error> {
@@ -69,7 +69,7 @@ impl ConfigReload {
     }
 
     /// Compute a diff between the current configuration and the given one,
-    /// and send the computed [`ConfigUpdate`]s to the [`crate::supervisor::Supervisor`].
+    /// and send the computed [`ConfigUpdate`]s to the supervisor.
     pub fn update_config(&self, new: Config) -> Result<bool, Error> {
         let updates = self.compute_updates(&new)?;
 

diff --git a/relayer/src/lib.rs b/relayer/src/lib.rs
@@ -1,5 +1,6 @@
 #![forbid(unsafe_code)]
 #![deny(
+    warnings,
     trivial_casts,
     trivial_numeric_casts,
     unused_import_braces,

diff --git a/relayer/src/link.rs b/relayer/src/link.rs
@@ -16,7 +16,7 @@ use crate::link::error::LinkError;
 use crate::link::relay_path::RelayPath;
 
 pub mod error;
-mod operational_data;
+pub mod operational_data;
 mod pending;
 mod relay_path;
 mod relay_sender;

diff --git a/relayer/src/object.rs b/relayer/src/object.rs
@@ -134,8 +134,8 @@ impl Packet {
 /// An object determines the amount of parallelism that can
 /// be exercised when processing [`IbcEvent`](ibc::events::IbcEvent)
 /// between two chains. For each [`Object`], a corresponding
-/// [`Worker`](crate::worker::Worker) is spawned and all [`IbcEvent`](ibc::events::IbcEvent)s mapped
-/// to an [`Object`] are sent to the associated [`Worker`](crate::worker::Worker)
+/// [`WorkerHandle`](crate::worker::WorkerHandle) is spawned and all [`IbcEvent`](ibc::events::IbcEvent)s mapped
+/// to an [`Object`] are sent to the associated [`WorkerHandle`](crate::worker::WorkerHandle)
 /// for processing.
 #[derive(Clone, Debug, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)]
 #[serde(tag = "type")]
@@ -187,7 +187,7 @@ define_error! {
 }
 
 impl Object {
-    /// Returns `true` if this [`Object`] is for a [`Worker`](crate::worker::Worker)
+    /// Returns `true` if this [`Object`] is for a [`WorkerHandle`](crate::worker::WorkerHandle)
     /// which is interested in new block events originating from the chain with
     /// the given [`ChainId`]. Returns `false` otherwise.
     pub fn notify_new_block(&self, src_chain_id: &ChainId) -> bool {

diff --git a/relayer/src/supervisor.rs b/relayer/src/supervisor.rs
@@ -17,7 +17,7 @@ use ibc::{
 
 use crate::{
     chain::{handle::ChainHandle, HealthCheck},
-    config::{ChainConfig, Config},
+    config::{ChainConfig, Config, SharedConfig},
     event::{
         self,
         monitor::{Error as EventError, ErrorDetail as EventErrorDetail, EventBatch},
@@ -84,7 +84,7 @@ pub struct SupervisorOptions {
    value is dropped.
 */
 pub fn spawn_supervisor(
-    config: Arc<RwLock<Config>>,
+    config: SharedConfig,
     registry: SharedRegistry<impl ChainHandle>,
     rest_rx: Option<rest::Receiver>,
     options: SupervisorOptions,
@@ -382,7 +382,7 @@ fn collect_event<F>(
     }
 }
 
-fn collect_events(
+pub fn collect_events(
     config: &Config,
     workers: &WorkerMap,
     src_chain: &impl ChainHandle,
@@ -840,7 +840,7 @@ fn update_config<Chain: ChainHandle>(
     }
 }
 
-/// Describes the result of [`collect_events`](Supervisor::collect_events).
+/// Describes the result of [`collect_events`].
 #[derive(Clone, Debug)]
 pub struct CollectedEvents {
     /// The height at which these events were emitted from the chain.

diff --git a/relayer/src/supervisor/spawn.rs b/relayer/src/supervisor/spawn.rs
@@ -21,7 +21,7 @@ use super::{
     Error,
 };
 
-/// A context for spawning workers within the [`crate::supervisor::Supervisor`].
+/// A context for spawning workers within the supervisor.
 pub struct SpawnContext<'a, Chain: ChainHandle> {
     config: &'a Config,
     registry: &'a mut Registry<Chain>,
@@ -186,7 +186,7 @@ impl<'a, Chain: ChainHandle> SpawnContext<'a, Chain> {
         }
     }
 
-    /// Spawns all the [`Worker`](crate::worker::Worker)s that will
+    /// Spawns all the [`WorkerHandle`](crate::worker::WorkerHandle)s that will
     /// handle a given channel for a given source chain.
     pub fn spawn_workers_for_channel(
         &mut self,

diff --git a/relayer/src/util/task.rs b/relayer/src/util/task.rs
@@ -142,7 +142,7 @@ impl TaskHandle {
 
        Note that because the background tasks are meant to run forever,
        this would likely never return unless errors occurred or if
-       the step runner returns [`TaskError::Abort`] to abort prematurely.
+       the step runner returns [`Next::Abort`] to abort prematurely.
     */
     pub fn join(mut self) {
         if let Some(handle) = mem::take(&mut self.join_handle.0) {

diff --git a/relayer/src/worker/cmd.rs b/relayer/src/worker/cmd.rs
@@ -2,7 +2,7 @@ use ibc::{core::ics02_client::events::NewBlock, Height};
 
 use crate::event::monitor::EventBatch;
 
-/// A command for a [`Worker`](crate::worker::Worker).
+/// A command for a [`WorkerHandle`](crate::worker::WorkerHandle).
 #[derive(Debug, Clone)]
 pub enum WorkerCmd {
     /// A batch of packet events need to be relayed

diff --git a/relayer/src/worker/map.rs b/relayer/src/worker/map.rs
@@ -15,7 +15,7 @@ use crate::{
 
 use super::{spawn_worker_tasks, WorkerHandle, WorkerId};
 
-/// Manage the lifecycle of [`Worker`]s associated with [`Object`]s.
+/// Manage the lifecycle of [`WorkerHandle`]s associated with [`Object`]s.
 #[derive(Debug)]
 pub struct WorkerMap {
     workers: HashMap<Object, WorkerHandle>,
@@ -34,17 +34,17 @@ impl Default for WorkerMap {
 impl WorkerMap {
     /// Create a new worker map, which will spawn workers with
     /// the given channel for sending messages back to the
-    /// [`Supervisor`](crate::supervisor::Supervisor).
+    /// [supervisor](crate::supervisor::SupervisorHandle).
     pub fn new() -> Self {
         Self::default()
     }
 
-    /// Returns `true` if there is a spawned [`Worker`] associated with the given [`Object`].
+    /// Returns `true` if there is a spawned [`WorkerHandle`] associated with the given [`Object`].
     pub fn contains(&self, object: &Object) -> bool {
         self.workers.contains_key(object)
     }
 
-    /// Remove the [`Worker`] associated with the given [`Object`] from
+    /// Remove the [`WorkerHandle`] associated with the given [`Object`] from
     /// the map and wait for its thread to terminate.
     pub fn remove_stopped(&mut self, id: WorkerId, object: Object) -> bool {
         match self.workers.remove(&object) {
@@ -89,7 +89,7 @@ impl WorkerMap {
         }
     }
 
-    /// Returns all the [`Worker`] which are interested in new block events originating
+    /// Returns all the [`WorkerHandle`] which are interested in new block events originating
     /// from the chain with the given [`ChainId`].
     /// See: [`Object::notify_new_block`]
     pub fn to_notify<'a>(
@@ -116,7 +116,7 @@ impl WorkerMap {
     /// Get a handle to the worker in charge of handling events associated
     /// with the given [`Object`].
     ///
-    /// This function will spawn a new [`Worker`] if one does not exists already.
+    /// This function will spawn a new [`WorkerHandle`] if one does not exists already.
     pub fn get_or_spawn<Chain: ChainHandle>(
         &mut self,
         object: Object,
@@ -132,7 +132,7 @@ impl WorkerMap {
         }
     }
 
-    /// Spawn a new [`Worker`], only if one does not exists already.
+    /// Spawn a new [`WorkerHandle`], only if one does not exists already.
     ///
     /// Returns whether or not the worker was actually spawned.
     pub fn spawn<Chain: ChainHandle>(

diff --git a/tools/integration-test/src/lib.rs b/tools/integration-test/src/lib.rs
@@ -1,3 +1,4 @@
+#![deny(warnings)]
 #![allow(clippy::too_many_arguments)]
 #![allow(clippy::type_complexity)]
 #![doc = include_str!("../README.md")]

diff --git a/tools/integration-test/src/types/binary/chains.rs b/tools/integration-test/src/types/binary/chains.rs
@@ -192,7 +192,8 @@ impl<ChainA: ChainHandle, ChainB: ChainHandle> ExportEnv for ConnectedChains<Cha
    Newtype wrapper for [`ChainHandle`] to stop the chain handle when
    this value is dropped.
 
-   Note that we cannot stop the chain on drop for [`ProdChainHandle`]
+   Note that we cannot stop the chain on drop for
+   [`ProdChainHandle`](ibc_relayer::chain::handle::ProdChainHandle)
    itself, as the chain handles can be cloned. But for testing purposes,
    we alway stop the chain handle when this "canonical" chain handle
    is dropped.