Repository: holochain/holochain (language: rust)

Issue:
Remove todo comments from cargo docs
There are many "TODO" and "@todo" comments that are rendered in cargo docs. They should be converted to comments that don't render in cargo docs.

AC:
- Review all todo comments appearing in cargo docs (i.e. in `///` comments)
- Modify them to not appear in cargo docs (i.e. move from `///` comments into `//` comments)


Discussion / hints:

Fix patch:
diff --git a/crates/fixt/CHANGELOG.md b/crates/fixt/CHANGELOG.md
index 483dd28a48..0065207273 100644
--- a/crates/fixt/CHANGELOG.md
+++ b/crates/fixt/CHANGELOG.md
@@ -6,6 +6,7 @@ default_semver_increment_mode: !pre_minor dev
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased](https://github.com/holochain/holochain/compare/fixt-v0.0.2-alpha.1...HEAD)
+- Prevent "TODO" comments from being rendered in cargo docs.
 
 ## 0.5.0-dev.0
 
diff --git a/crates/fixt/src/serialized_bytes.rs b/crates/fixt/src/serialized_bytes.rs
index 6be565ec38..730210f296 100644
--- a/crates/fixt/src/serialized_bytes.rs
+++ b/crates/fixt/src/serialized_bytes.rs
@@ -1,4 +1,4 @@
-//! @todo move all this out to the serialized bytes crate
+// @todo move all this out to the serialized bytes crate
 use crate::prelude::*;
 use holochain_serialized_bytes::prelude::*;
 use rand::seq::SliceRandom;
diff --git a/crates/hdi/CHANGELOG.md b/crates/hdi/CHANGELOG.md
index 241e891f48..1a7c37cd04 100644
--- a/crates/hdi/CHANGELOG.md
+++ b/crates/hdi/CHANGELOG.md
@@ -6,6 +6,7 @@ default_semver_increment_mode: !pre_minor dev
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## Unreleased
+- Prevent "TODO" comments from being rendered in cargo docs.
 
 ## 0.6.0-dev.13
 
diff --git a/crates/hdi/src/entry.rs b/crates/hdi/src/entry.rs
index 92435b4eff..04d7c3f74d 100644
--- a/crates/hdi/src/entry.rs
+++ b/crates/hdi/src/entry.rs
@@ -20,8 +20,8 @@ pub mod examples;
 /// [`must_get_entry`] is available in contexts such as validation where both determinism and network access is desirable.
 ///
 /// An EntryHashed will NOT be returned if:
-/// - @TODO It is PURGED (community redacted entry)
-/// - @TODO ALL actions pointing to it are WITHDRAWN by the authors
+// - @TODO It is PURGED (community redacted entry)
+// - @TODO ALL actions pointing to it are WITHDRAWN by the authors
 /// - ALL actions pointing to it are ABANDONED by ALL authorities due to validation failure
 /// - Nobody knows about it on the currently visible network
 ///
@@ -49,8 +49,8 @@ pub fn must_get_entry(entry_hash: EntryHash) -> ExternResult<EntryHashed> {
 ///
 /// A [`SignedActionHashed`] will NOT be returned if:
 ///
-/// - @TODO The action is WITHDRAWN by the author
-/// - @TODO The action is ABANDONED by ALL authorities
+// - @TODO The action is WITHDRAWN by the author
+// - @TODO The action is ABANDONED by ALL authorities
 /// - Nobody knows about it on the currently visible network
 ///
 /// If a [`SignedActionHashed`] fails to be returned:
@@ -82,10 +82,10 @@ pub fn must_get_action(action_hash: ActionHash) -> ExternResult<SignedActionHash
 /// Note though that each "hop" in recursive validation is routed to a completely different set of authorities.
 /// It does not take many hops to reach the point where an attacker needs to eclipse the entire network to lie about [`Record`] validity.
 ///
-/// @TODO We keep signed receipts from authorities serving up "valid records".
-/// - If we ever discover a record we were told is valid is invalid we can retroactively look to warrant authorities
-/// - We can async (e.g. in a background task) be recursively validating [`Record`] dependencies ourselves, following hops until there is no room for lies
-/// - We can with small probability recursively validate to several hops inline to discourage potential eclipse attacks with a credible immediate threat
+// @TODO We keep signed receipts from authorities serving up "valid records".
+// - If we ever discover a record we were told is valid is invalid we can retroactively look to warrant authorities
+// - We can async (e.g. in a background task) be recursively validating [`Record`] dependencies ourselves, following hops until there is no room for lies
+// - We can with small probability recursively validate to several hops inline to discourage potential eclipse attacks with a credible immediate threat
 ///
 /// If you do not care about validity and simply want a pair of [`Action`]+[`Entry`] data, then use both [`must_get_action`] and [`must_get_entry`] together.
 ///
@@ -93,8 +93,8 @@ pub fn must_get_action(action_hash: ActionHash) -> ExternResult<SignedActionHash
 ///
 /// An [`Record`] will not be returned if:
 ///
-/// - @TODO It is WITHDRAWN by the author
-/// - @TODO The Entry is PURGED by the community
+// - @TODO It is WITHDRAWN by the author
+// - @TODO The Entry is PURGED by the community
 /// - It is ABANDONED by ALL authorities due to failed validation
 /// - If ANY authority (1 of N trust) OR ourselves (0 of N trust) believes it INVALID
 /// - Nobody knows about it on the visible network
diff --git a/crates/hdi/src/hash.rs b/crates/hdi/src/hash.rs
index dce39a20ae..1d21333ff0 100644
--- a/crates/hdi/src/hash.rs
+++ b/crates/hdi/src/hash.rs
@@ -173,7 +173,7 @@ use crate::prelude::*;
 /// layer, so we want to re-use that as much as possible.
 /// The action hash can be extracted from the Record as `record.action_hashed().as_hash()`.
 ///
-/// @todo is there any use-case that can't be satisfied by the `action_hashed` approach?
+// @todo is there any use-case that can't be satisfied by the `action_hashed` approach?
 ///
 /// Anything that is annotated with #[hdk_entry_helper] implements this so is compatible automatically.
 ///
@@ -233,7 +233,7 @@ pub fn hash_blake2b(input: Vec<u8>, output_len: u8) -> ExternResult<Vec<u8>> {
     }
 }
 
-/// @todo - not implemented on the host
+// @todo - not implemented on the host
 pub fn hash_sha256(input: Vec<u8>) -> ExternResult<Vec<u8>> {
     match HDI.with(|h| h.borrow().hash(HashInput::Sha256(input)))? {
         HashOutput::Sha256(hash) => Ok(hash.as_ref().to_vec()),
@@ -241,7 +241,7 @@ pub fn hash_sha256(input: Vec<u8>) -> ExternResult<Vec<u8>> {
     }
 }
 
-/// @todo - not implemented on the host
+// @todo - not implemented on the host
 pub fn hash_sha512(input: Vec<u8>) -> ExternResult<Vec<u8>> {
     match HDI.with(|h| h.borrow().hash(HashInput::Sha512(input)))? {
         HashOutput::Sha512(hash) => Ok(hash.as_ref().to_vec()),
diff --git a/crates/hdi/src/hash_path/shard.rs b/crates/hdi/src/hash_path/shard.rs
index 8a4bb2f71f..6fa28596b4 100644
--- a/crates/hdi/src/hash_path/shard.rs
+++ b/crates/hdi/src/hash_path/shard.rs
@@ -19,7 +19,7 @@ pub type ShardDepth = u32;
 /// At the moment sharding only works well for data that is reliably longer than width/depth.
 /// For example, sharding the username foo with width 4 doesn't make sense.
 /// There is no magic padding or extending of the provided data to make up undersized shards.
-/// @todo stretch short shards out in a nice balanced way (append some bytes from the hash?)
+// @todo stretch short shards out in a nice balanced way (append some bytes from the hash?)
 pub struct ShardStrategy(ShardWidth, ShardDepth);
 
 /// impl [`ShardStrategy`] as an immutable/read-only thingy.
diff --git a/crates/hdi/src/lib.rs b/crates/hdi/src/lib.rs
index e4c634b189..7595290f7b 100644
--- a/crates/hdi/src/lib.rs
+++ b/crates/hdi/src/lib.rs
@@ -271,10 +271,11 @@ pub mod prelude;
 /// This is also repudiable so both participants know the data must have been encrypted by the other (because they didn't encrypt it themselves) but cannot prove this to anybody else (because they _could have_ encrypted it themselves).
 /// If repudiability is not something you want, you need to use a different approach.
 ///
-/// Note that the secrets are located within the secure lair keystore (@todo actually secretbox puts the secret in WASM, but this will be fixed soon) and never touch WASM memory.
+/// Note that the secrets are located within the secure lair keystore and never touch WASM memory.
+// @todo actually secretbox puts the secret in WASM, but this will be fixed soon
 /// The WASM must provide either the public key for box or an opaque _reference_ to the secret key so that lair can encrypt or decrypt as required.
 ///
-/// @todo implement a way to export/send an encrypted shared secret for a peer from lair
+// @todo implement a way to export/send an encrypted shared secret for a peer from lair
 ///
 /// Note that even though the elliptic curve is the same as is used by ed25519, the keypairs cannot be shared because the curve is mathematically translated in the signing vs. encryption algorithms.
 /// In theory the keypairs could also be translated to move between the two algorithms but Holochain doesn't offer a way to do this (yet?).
diff --git a/crates/hdk/CHANGELOG.md b/crates/hdk/CHANGELOG.md
index da687d3b5d..ce60e5d5d1 100644
--- a/crates/hdk/CHANGELOG.md
+++ b/crates/hdk/CHANGELOG.md
@@ -6,6 +6,7 @@ default_semver_increment_mode: !pre_minor dev
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## Unreleased
+- Prevent "TODO" comments from being rendered in cargo docs.
 
 ## 0.5.0-dev.16
 
diff --git a/crates/hdk/src/chain.rs b/crates/hdk/src/chain.rs
index 8a1e949f47..665d1a7866 100644
--- a/crates/hdk/src/chain.rs
+++ b/crates/hdk/src/chain.rs
@@ -22,12 +22,12 @@ pub fn get_agent_activity(
 ///
 /// Given an action and entry type, returns an [ `Vec<Record>` ]
 ///
-/// @todo document this better with examples after we make query do all the things we want.
-/// @todo implement cap grant/claim usage in terms of query
-/// @todo have ability to hash-bound query other agent's chains based on agent activity
-/// @todo tie query into validation so we track dependencies e.g. validation packages
-/// @todo decide which direction we want to iterate in (paramaterise query?)
-/// @todo more expresivity generally?
+// @todo document this better with examples after we make query do all the things we want.
+// @todo implement cap grant/claim usage in terms of query
+// @todo have ability to hash-bound query other agent's chains based on agent activity
+// @todo tie query into validation so we track dependencies e.g. validation packages
+// @todo decide which direction we want to iterate in (paramaterise query?)
+// @todo more expresivity generally?
 pub fn query(filter: ChainQueryFilter) -> ExternResult<Vec<Record>> {
     HDK.with(|h| h.borrow().query(filter))
 }
diff --git a/crates/hdk/src/entry.rs b/crates/hdk/src/entry.rs
index 4ee05c9801..5dfca637b3 100644
--- a/crates/hdk/src/entry.rs
+++ b/crates/hdk/src/entry.rs
@@ -181,12 +181,12 @@ where
 /// See [`get_details`] for more information about how CRUD records reference each other.
 ///
 /// Note: [`get`] __always triggers and blocks on a network call__.
-///       @todo implement a 'get optimistic' that returns based on the current opinion of the world
-///       and performs network calls in the background so they are available 'next time'.
+//       @todo implement a 'get optimistic' that returns based on the current opinion of the world
+//       and performs network calls in the background so they are available 'next time'.
 ///
 /// Note: Deletes are considered in the liveness but Updates are not currently followed
 ///       automatically due to the need for the happ to disambiguate update logic.
-///       @todo implement 'redirect' logic so that updates are followed by [`get`].
+//       @todo implement 'redirect' logic so that updates are followed by [`get`].
 ///
 /// Note: Updates typically point to a different entry hash than what they are updating but not
 ///       always, e.g. consider changing `foo` to `bar` back to `foo`. The entry hashes in a crud
diff --git a/crates/hdk/src/lib.rs b/crates/hdk/src/lib.rs
index 3ef9c5a7df..2ba70ff7fd 100644
--- a/crates/hdk/src/lib.rs
+++ b/crates/hdk/src/lib.rs
@@ -450,7 +450,8 @@ pub mod prelude;
 /// This is also repudiable so both participants know the data must have been encrypted by the other (because they didn't encrypt it themselves) but cannot prove this to anybody else (because they _could have_ encrypted it themselves).
 /// If repudiability is not something you want, you need to use a different approach.
 ///
-/// Note that the secrets are located within the secure lair keystore (@todo actually secretbox puts the secret in WASM, but this will be fixed soon) and never touch WASM memory.
+/// Note that the secrets are located within the secure lair keystore and never touch WASM memory.
+// @todo actually secretbox puts the secret in WASM, but this will be fixed soon
 /// The WASM must provide either the public key for box or an opaque _reference_ to the secret key so that lair can encrypt or decrypt as required.
 //
 // @todo implement a way to export/send an encrypted shared secret for a peer from lair
diff --git a/crates/hdk/src/time.rs b/crates/hdk/src/time.rs
index cb546f0482..8a7616dfab 100644
--- a/crates/hdk/src/time.rs
+++ b/crates/hdk/src/time.rs
@@ -31,35 +31,35 @@ use crate::prelude::*;
 /// guarantee that it is seeing the same time as the rust host, so this enables stricter validation
 /// logic.
 ///
-/// @todo
-/// Sys times aren't the final word on secure times, for another option it may be best to use the
-/// roughtime protocol which redundantly fetches cryptographically signed times from multiple
-/// different servers and cross-references them.
-/// There is a POC for this but it's not in core yet (requires at least UDP calls from the host).
-/// Note that the **redundant fetching** and **cross-referencing** parts are critical, even though
-/// they add a lot of complexity to the protocol. Failure to do this brought down the ETH2.0
-/// Medalla testnet due to a single roughtime server from cloudflare being 24 hours off.
-/// Note also that roughtime, or any other "secure timestamping" option requires the agent to be
-/// online at the time of generating times, which runs counter to the requirement that holochain
-/// support "agent centric, offline first" behaviour, but may be acceptable or even a neccessary
-/// evil for specific application logic.
-/// The other challenge with roughtime is list management to track the list of valid servers over
-/// time, which might rely on agents providing snapshots of links to public keys (i.e. representing
-/// the roughtime ecosystem itself in a happ).
-///
-/// See <https://blog.cloudflare.com/roughtime/>
-///
-/// @todo
-/// Another option is to use proof of work style constructions to roughly throttle the speed that
-/// things can be done without relying on absolute times, or even that users experience the same
-/// throttling due to differences in CPU/GPU performance on the POW algorithm.
-/// See <https://zkga.me/> uses this as a game mechanic
-///
-/// @todo
-/// Other p2p type time syncing algorithms that allow peers to adjust their clock offsets to agree
-/// on the current time within relatively tight accuracy/precision up-front in a relatively trusted
-/// environment e.g. a chess game between friends with time moves that balances security/trust and
-/// flaky networking, etc.
+// @todo
+// Sys times aren't the final word on secure times, for another option it may be best to use the
+// roughtime protocol which redundantly fetches cryptographically signed times from multiple
+// different servers and cross-references them.
+// There is a POC for this but it's not in core yet (requires at least UDP calls from the host).
+// Note that the **redundant fetching** and **cross-referencing** parts are critical, even though
+// they add a lot of complexity to the protocol. Failure to do this brought down the ETH2.0
+// Medalla testnet due to a single roughtime server from cloudflare being 24 hours off.
+// Note also that roughtime, or any other "secure timestamping" option requires the agent to be
+// online at the time of generating times, which runs counter to the requirement that holochain
+// support "agent centric, offline first" behaviour, but may be acceptable or even a neccessary
+// evil for specific application logic.
+// The other challenge with roughtime is list management to track the list of valid servers over
+// time, which might rely on agents providing snapshots of links to public keys (i.e. representing
+// the roughtime ecosystem itself in a happ).
+//
+// See <https://blog.cloudflare.com/roughtime/>
+//
+// @todo
+// Another option is to use proof of work style constructions to roughly throttle the speed that
+// things can be done without relying on absolute times, or even that users experience the same
+// throttling due to differences in CPU/GPU performance on the POW algorithm.
+// See <https://zkga.me/> uses this as a game mechanic
+//
+// @todo
+// Other p2p type time syncing algorithms that allow peers to adjust their clock offsets to agree
+// on the current time within relatively tight accuracy/precision up-front in a relatively trusted
+// environment e.g. a chess game between friends with time moves that balances security/trust and
+// flaky networking, etc.
 pub fn sys_time() -> ExternResult<Timestamp> {
     HDK.with(|h| h.borrow().sys_time(()))
 }
diff --git a/crates/hdk/src/x_salsa20_poly1305.rs b/crates/hdk/src/x_salsa20_poly1305.rs
index 2cbacab64d..487b57a709 100644
--- a/crates/hdk/src/x_salsa20_poly1305.rs
+++ b/crates/hdk/src/x_salsa20_poly1305.rs
@@ -74,7 +74,7 @@ pub fn x_salsa20_poly1305_shared_secret_ingest(
 ///  - Secretbox is designed for 'small' data, break large data into chunks with unique nonces.
 ///  - Secretbox is NOT quantum resistant.
 ///
-/// @todo shift all the secret handling into lair so that we only work with opaque key references.
+// @todo shift all the secret handling into lair so that we only work with opaque key references.
 ///
 /// If you want to hide data:
 ///  - Consider using capability tokens and/or dedicated DHT networks to control access.
diff --git a/crates/holochain/CHANGELOG.md b/crates/holochain/CHANGELOG.md
index a810b3af36..e905354181 100644
--- a/crates/holochain/CHANGELOG.md
+++ b/crates/holochain/CHANGELOG.md
@@ -7,8 +7,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
 ## Unreleased
 - Change most enums that are exposed via the conductor API to be serialized with `tag = "type"` and `content = "value"` #4616
-
 - Replace `tiny-keccak` with `sha3` due to dependency on problematic `crunchy` crate
+- Prevent "TODO" comments from being rendered in cargo docs.
 
 ## 0.5.0-dev.17
 
diff --git a/crates/holochain/src/core/ribosome.rs b/crates/holochain/src/core/ribosome.rs
index df864bd4a4..2731f7afa7 100644
--- a/crates/holochain/src/core/ribosome.rs
+++ b/crates/holochain/src/core/ribosome.rs
@@ -669,14 +669,14 @@ pub trait RibosomeT: Sized + std::fmt::Debug + Send + Sync {
     /// values without needing to make holochain a dependency.
     async fn get_const_fn(&self, zome: &Zome, name: &str) -> Result<Option<i32>, RibosomeError>;
 
-    /// @todo list out all the available callbacks and maybe cache them somewhere
+    // @todo list out all the available callbacks and maybe cache them somewhere
     fn list_callbacks(&self) {
         unimplemented!()
         // pseudocode
         // self.instance().exports().filter(|e| e.is_callback())
     }
 
-    /// @todo list out all the available zome functions and maybe cache them somewhere
+    // @todo list out all the available zome functions and maybe cache them somewhere
     fn list_zome_fns(&self) {
         unimplemented!()
         // pseudocode
diff --git a/crates/holochain/src/core/ribosome/host_fn/accept_countersigning_preflight_request.rs b/crates/holochain/src/core/ribosome/host_fn/accept_countersigning_preflight_request.rs
index 0107a6e34d..ec2b764039 100644
--- a/crates/holochain/src/core/ribosome/host_fn/accept_countersigning_preflight_request.rs
+++ b/crates/holochain/src/core/ribosome/host_fn/accept_countersigning_preflight_request.rs
@@ -1009,11 +1009,11 @@ pub mod wasm_test {
 
     #[tokio::test(flavor = "multi_thread")]
     #[ignore = "flaky"]
-    /// TODO: this test and the following one (`enzymatic_session_success_forced_init`) form a pair.
-    /// The latter includes a "fix" to the test to remove the flakiness, but the flakiness itself is a problem
-    /// that we need to address.
-    /// The flakiness is described in https://github.com/holochain/holochain/pull/3046. When that is resolved,
-    /// this test can be unignored, and the companion test can be removed.
+    // TODO: this test and the following one (`enzymatic_session_success_forced_init`) form a pair.
+    // The latter includes a "fix" to the test to remove the flakiness, but the flakiness itself is a problem
+    // that we need to address.
+    // The flakiness is described in https://github.com/holochain/holochain/pull/3046. When that is resolved,
+    // this test can be unignored, and the companion test can be removed.
     async fn enzymatic_session_success_flaky() {
         enzymatic_session_success(false).await
     }
diff --git a/crates/holochain_integrity_types/CHANGELOG.md b/crates/holochain_integrity_types/CHANGELOG.md
index 8f014a04e8..e985ae2dcf 100644
--- a/crates/holochain_integrity_types/CHANGELOG.md
+++ b/crates/holochain_integrity_types/CHANGELOG.md
@@ -6,6 +6,7 @@ default_semver_increment_mode: !pre_minor dev
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## Unreleased
+- Prevent "TODO" comments from being rendered in cargo docs.
 
 ## 0.5.0-dev.11
 
diff --git a/crates/holochain_integrity_types/src/capability/secret.rs b/crates/holochain_integrity_types/src/capability/secret.rs
index 3c5a4bf3fa..cdaff3531d 100644
--- a/crates/holochain_integrity_types/src/capability/secret.rs
+++ b/crates/holochain_integrity_types/src/capability/secret.rs
@@ -14,7 +14,7 @@ pub type CapSecretBytes = [u8; CAP_SECRET_BYTES];
 /// the grantor to allow access to others. The grantor can optionally further restrict usage of the
 /// secret to specific agents.
 ///
-/// @todo enforce that secrets are unique across all grants in a chain.
+// @todo enforce that secrets are unique across all grants in a chain.
 // The PartialEq impl by subtle *should* be compatible with default Hash impl
 #[allow(clippy::derived_hash_with_manual_eq)]
 #[derive(Clone, Copy, Hash, SerializedBytes)]
diff --git a/crates/holochain_secure_primitive/CHANGELOG.md b/crates/holochain_secure_primitive/CHANGELOG.md
index 40bbe7649a..a27ea879b2 100644
--- a/crates/holochain_secure_primitive/CHANGELOG.md
+++ b/crates/holochain_secure_primitive/CHANGELOG.md
@@ -6,6 +6,7 @@ default_semver_increment_mode: !pre_minor dev
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## \[Unreleased\]
+- Prevent "TODO" comments from being rendered in cargo docs.
 
 ## 0.5.0-dev.0
 
diff --git a/crates/holochain_secure_primitive/src/lib.rs b/crates/holochain_secure_primitive/src/lib.rs
index d233b19611..5533cc7e6c 100644
--- a/crates/holochain_secure_primitive/src/lib.rs
+++ b/crates/holochain_secure_primitive/src/lib.rs
@@ -96,15 +96,15 @@ macro_rules! fixed_array_serialization {
 ///
 /// MITM attacks are mitigated by the networking implementation itself.
 ///
-/// @todo given how impossible it is for wasm to protect its memory from the host, it would make
-/// more sense to:
-///
-///  - use key exchange protocols like libsodium kx <https://libsodium.gitbook.io/doc/key_exchange>.
-///  - keep secrets inside lair with all algorithms behind an API, wasm only has access to opaque
-///    references to the secret data.
-///
-/// @todo implement explicit zeroing, moving and copying of memory for sensitive data.
-///       - e.g. the secrecy crate <https://crates.io/crates/secrecy>
+// @todo given how impossible it is for wasm to protect its memory from the host, it would make
+// more sense to:
+//
+//  - use key exchange protocols like libsodium kx <https://libsodium.gitbook.io/doc/key_exchange>.
+//  - keep secrets inside lair with all algorithms behind an API, wasm only has access to opaque
+//    references to the secret data.
+//
+// @todo implement explicit zeroing, moving and copying of memory for sensitive data.
+//       - e.g. the secrecy crate <https://crates.io/crates/secrecy>
 macro_rules! secure_primitive {
     ($t:ty, $len:expr) => {
         $crate::fixed_array_serialization!($t, $len);
diff --git a/crates/holochain_sqlite/CHANGELOG.md b/crates/holochain_sqlite/CHANGELOG.md
index f97b926070..7eedd5d8ae 100644
--- a/crates/holochain_sqlite/CHANGELOG.md
+++ b/crates/holochain_sqlite/CHANGELOG.md
@@ -6,6 +6,7 @@ default_semver_increment_mode: !pre_minor dev
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## \[Unreleased\]
+- Prevent "TODO" comments from being rendered in cargo docs.
 
 ## 0.5.0-dev.16
 
diff --git a/crates/holochain_sqlite/src/db/databases.rs b/crates/holochain_sqlite/src/db/databases.rs
index 90375fe1bd..b739355939 100644
--- a/crates/holochain_sqlite/src/db/databases.rs
+++ b/crates/holochain_sqlite/src/db/databases.rs
@@ -29,9 +29,9 @@ pub(super) static DATABASE_HANDLES: Lazy<Databases> = Lazy::new(|| {
         eprintln!("FATAL PANIC {:#?}", panic_info);
         // invoke the original handler
         orig_handler(panic_info);
-        // // Abort the process
-        // // TODO - we need a better solution than this, but if there is
-        // // no better solution, we can uncomment the following line:
+        // Abort the process
+        // TODO - we need a better solution than this, but if there is
+        //  no better solution, we can uncomment the following line:
         // std::process::abort();
     }));
 
diff --git a/crates/holochain_types/CHANGELOG.md b/crates/holochain_types/CHANGELOG.md
index db350f3d6e..86aed8d592 100644
--- a/crates/holochain_types/CHANGELOG.md
+++ b/crates/holochain_types/CHANGELOG.md
@@ -6,6 +6,7 @@ default_semver_increment_mode: !pre_minor dev
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## \[Unreleased\]
+- Prevent "TODO" comments from being rendered in cargo docs.
 
 ## 0.5.0-dev.17
 
diff --git a/crates/holochain_types/src/dht_op.rs b/crates/holochain_types/src/dht_op.rs
index 01267404c2..02f5c050cc 100644
--- a/crates/holochain_types/src/dht_op.rs
+++ b/crates/holochain_types/src/dht_op.rs
@@ -34,7 +34,8 @@ mod tests;
 pub enum DhtOp {
     /// An op representing storage of some record information.
     ChainOp(Box<ChainOp>),
-    /// TODO, new type of op
+    /// A op representing storage of a claim that a ChainOp was invalid
+    // TODO, new type of op
     WarrantOp(Box<WarrantOp>),
 }
 
diff --git a/crates/holochain_types/src/dna/dna_file.rs b/crates/holochain_types/src/dna/dna_file.rs
index 9e8e557522..f3eb1ddc98 100644
--- a/crates/holochain_types/src/dna/dna_file.rs
+++ b/crates/holochain_types/src/dna/dna_file.rs
@@ -47,10 +47,10 @@ impl From<WasmMapSerialized> for WasmMap {
 /// That function has been superseded by `DnaBundle`, but we use this type
 /// widely, so there is simply a way to convert from `DnaBundle` to `DnaFile`.
 ///
-/// TODO: Once we remove the `InstallApp` command which accepts a `DnaFile`,
-///       we should remove the Serialize impl on this type, and perhaps rename
-///       to indicate that this is simply a validated, fully-formed DnaBundle
-///       (i.e. all Wasms are bundled and immediately available, not remote.)
+// TODO: Once we remove the `InstallApp` command which accepts a `DnaFile`,
+//       we should remove the Serialize impl on this type, and perhaps rename
+//       to indicate that this is simply a validated, fully-formed DnaBundle
+//       (i.e. all Wasms are bundled and immediately available, not remote.)
 #[derive(Serialize, Deserialize, Clone, PartialEq, Eq, SerializedBytes, Hash)]
 pub struct DnaFile {
     /// The hashable portion that can be shared with hApp code.
diff --git a/crates/holochain_zome_types/CHANGELOG.md b/crates/holochain_zome_types/CHANGELOG.md
index 78f25ecfa1..d1341d28c1 100644
--- a/crates/holochain_zome_types/CHANGELOG.md
+++ b/crates/holochain_zome_types/CHANGELOG.md
@@ -6,6 +6,7 @@ default_semver_increment_mode: !pre_minor dev
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## \[Unreleased\]
+- Prevent "TODO" comments from being rendered in cargo docs.
 
 ## 0.5.0-dev.15
 
diff --git a/crates/holochain_zome_types/src/capability/grant.rs b/crates/holochain_zome_types/src/capability/grant.rs
index 63cc27360a..c9e94a4d07 100644
--- a/crates/holochain_zome_types/src/capability/grant.rs
+++ b/crates/holochain_zome_types/src/capability/grant.rs
@@ -2,6 +2,7 @@ use super::*;
 use holochain_serialized_bytes::SerializedBytes;
 use std::collections::BTreeMap;
 
+/// Map of zome functions to the payloads to curry into to them
+// @todo Ability to forcibly curry payloads into functions that are called with a claim.
 #[derive(Default, PartialEq, Eq, Debug, Clone, serde::Serialize, serde::Deserialize)]
-/// @todo Ability to forcibly curry payloads into functions that are called with a claim.
 pub struct CurryPayloads(pub BTreeMap<GrantedFunction, SerializedBytes>);
diff --git a/crates/holochain_zome_types/src/query.rs b/crates/holochain_zome_types/src/query.rs
index 884350221c..6e53e411b2 100644
--- a/crates/holochain_zome_types/src/query.rs
+++ b/crates/holochain_zome_types/src/query.rs
@@ -25,10 +25,10 @@ pub use holochain_serialized_bytes::prelude::*;
 /// records to return only. Technically the seq bounded ranges do not imply
 /// any fork disambiguation and so could be a range but for simplicity we left
 /// the API symmetrical in boundedness across all enum variants.
-/// @TODO It may be possible to provide/implement RangeBounds in the case that
-/// a full sequence of records/actions is provided but it would need to be
-/// handled as inclusive first, to enforce the integrity of the query, then the
-/// exclusiveness achieved by simply removing the final record after the fact.
+// TODO It may be possible to provide/implement RangeBounds in the case that
+// a full sequence of records/actions is provided but it would need to be
+// handled as inclusive first, to enforce the integrity of the query, then the
+// exclusiveness achieved by simply removing the final record after the fact.
 #[derive(serde::Serialize, serde::Deserialize, PartialEq, Clone, Debug)]
 pub enum ChainQueryFilterRange {
     /// Do NOT apply any range filtering for this query.
diff --git a/crates/kitsune_p2p/dht/CHANGELOG.md b/crates/kitsune_p2p/dht/CHANGELOG.md
index 490df92845..5dbb9d42d0 100644
--- a/crates/kitsune_p2p/dht/CHANGELOG.md
+++ b/crates/kitsune_p2p/dht/CHANGELOG.md
@@ -6,6 +6,7 @@ default_semver_increment_mode: !pre_minor dev
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## \[Unreleased\]
+- Prevent "TODO" comments from being rendered in cargo docs.
 
 ## 0.5.0-dev.2
 
diff --git a/crates/kitsune_p2p/dht/src/arq/peer_view.rs b/crates/kitsune_p2p/dht/src/arq/peer_view.rs
index 81e22bd5a3..743186cf00 100644
--- a/crates/kitsune_p2p/dht/src/arq/peer_view.rs
+++ b/crates/kitsune_p2p/dht/src/arq/peer_view.rs
@@ -59,9 +59,9 @@ impl PeerViewQ {
     }
 
     /// The actual coverage of all arcs in this view.
-    /// TODO: this only makes sense when the view contains all agents in the DHT.
-    ///       So, it's more useful for testing. Probably want to tease out some
-    ///       concept of a test DHT from this.
+    // TODO: this only makes sense when the view contains all agents in the DHT.
+    //       So, it's more useful for testing. Probably want to tease out some
+    //       concept of a test DHT from this.
     pub fn actual_coverage(&self) -> f64 {
         actual_coverage(&self.topo, self.peers.iter())
     }
@@ -75,8 +75,8 @@ impl PeerViewQ {
     /// These two are complected together simply for efficiency's sake, to
     /// minimize computation
     ///
-    /// TODO: this probably will be rewritten when PeerView is rewritten to
-    /// have the filter baked in.
+    // TODO: this probably will be rewritten when PeerView is rewritten to
+    // have the filter baked in.
     pub fn extrapolated_coverage_and_filtered_count(&self, filter: &Arq) -> (f64, usize) {
         let filter = filter.to_dht_arc(self.topo.space);
         if filter.is_empty() {
@@ -229,7 +229,7 @@ impl PeerViewQ {
     ///
     /// More detail on these assumptions here:
     /// <https://hackmd.io/@hololtd/r1IAIbr5Y/https%3A%2F%2Fhackmd.io%2FK_fkBj6XQO2rCUZRRL9n2g>
-    /// TODO: make the above link to something publicly available, preferably in the repo
+    // TODO: make the above link to something publicly available, preferably in the repo
     pub fn update_arq_with_stats(&self, arq: &mut Arq) -> UpdateArqStats {
         let topo = &self.topo;
         let (cov, num_peers) = self.extrapolated_coverage_and_filtered_count(arq);
diff --git a/crates/kitsune_p2p/dht/src/arq/strat.rs b/crates/kitsune_p2p/dht/src/arq/strat.rs
index 7df08803c5..7f6adefeec 100644
--- a/crates/kitsune_p2p/dht/src/arq/strat.rs
+++ b/crates/kitsune_p2p/dht/src/arq/strat.rs
@@ -67,7 +67,10 @@ pub struct ArqStrat {
     /// Note that this parameter does not guarantee that any agent's arq
     /// will have a power +/- this diff from our power, but we may decide to
     /// choose not to gossip with agents whose power falls outside the range
-    /// defined by this diff. TODO: do this.
+    /// defined by this diff.
+    ///
+    // TODO do not to gossip with agents whose power falls outside the range
+    // defined by this diff
     pub max_power_diff: u8,
 
     /// If at any time the number of peers seen by a node is less than the
@@ -85,7 +88,7 @@ pub struct ArqStrat {
     /// greater than this threshold, then we might do something different when
     /// it comes to our decision to requantize. For now, just print a warning.
     ///
-    /// TODO: this can probably be expressed in terms of `max_power_diff`.
+    // TODO: this can probably be expressed in terms of `max_power_diff`.
     pub power_std_dev_threshold: f64,
 
     /// Settings to override the global arc settings, for instance to mandate
diff --git a/crates/kitsune_p2p/dht/src/hash.rs b/crates/kitsune_p2p/dht/src/hash.rs
index f5a728a5b9..78cc261eca 100644
--- a/crates/kitsune_p2p/dht/src/hash.rs
+++ b/crates/kitsune_p2p/dht/src/hash.rs
@@ -1,6 +1,5 @@
 //! Simple hash types.
-//!
-//! TODO: unify with hashes from `kitsune_p2p_types::bin_types`
+// TODO: unify with hashes from `kitsune_p2p_types::bin_types`
 
 /// 32 bytes
 pub type Hash32 = [u8; 32];
diff --git a/crates/kitsune_p2p/kitsune_p2p/CHANGELOG.md b/crates/kitsune_p2p/kitsune_p2p/CHANGELOG.md
index 19f2245937..2fbf153eb4 100644
--- a/crates/kitsune_p2p/kitsune_p2p/CHANGELOG.md
+++ b/crates/kitsune_p2p/kitsune_p2p/CHANGELOG.md
@@ -6,6 +6,7 @@ default_semver_increment_mode: !pre_minor dev
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## \[Unreleased\]
+- Prevent "TODO" comments from being rendered in cargo docs.
 
 ## 0.5.0-dev.10
 
diff --git a/crates/kitsune_p2p/types/CHANGELOG.md b/crates/kitsune_p2p/types/CHANGELOG.md
index 81b6a432e2..3382d31ea7 100644
--- a/crates/kitsune_p2p/types/CHANGELOG.md
+++ b/crates/kitsune_p2p/types/CHANGELOG.md
@@ -6,6 +6,7 @@ default_semver_increment_mode: !pre_minor dev
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## \[Unreleased\]
+- Prevent "TODO" comments from being rendered in cargo docs.
 
 ## 0.5.0-dev.8
 
diff --git a/crates/kitsune_p2p/types/src/bootstrap.rs b/crates/kitsune_p2p/types/src/bootstrap.rs
index 744297833f..9f4c4bd2a7 100644
--- a/crates/kitsune_p2p/types/src/bootstrap.rs
+++ b/crates/kitsune_p2p/types/src/bootstrap.rs
@@ -6,7 +6,7 @@ use std::sync::Arc;
 
 /// The number of random agent infos we want to collect from the bootstrap service when we want to
 /// populate an empty local space.
-/// @todo expose this to network config.
+// @todo expose this to network config.
 const RANDOM_LIMIT_DEFAULT: u32 = 16;
 
 /// Struct to be encoded for the `random` op.


Test patch:
diff --git a/crates/holochain/src/core/sys_validate/tests.rs b/crates/holochain/src/core/sys_validate/tests.rs
index 602bb71038..886acb6f62 100644
--- a/crates/holochain/src/core/sys_validate/tests.rs
+++ b/crates/holochain/src/core/sys_validate/tests.rs
@@ -5,8 +5,6 @@
 //! - Any action other than DNA cannot be at seq 0
 //! - The DNA action can only be validated if the chain is empty,
 //!     and its timestamp must not be less than the origin time
-//!     (this "if chain not empty" thing is a bit weird,
-//!     TODO refactor to not look in the db)
 //! - Timestamps must increase monotonically
 //! - Sequence numbers must increment by 1 for each new action
 //! - Entry type in the action matches the entry variant
@@ -18,14 +16,16 @@
 //! - Check that StoreEntry never contains a private entry type
 //! - Test that a given sequence of actions constitutes a valid chain w.r.t. its backlinks
 //!
-//! TO TEST:
-//! - Create and Update Agent can only be preceded by AgentValidationPkg
-//! - Author must match the entry hash of the most recent Create/Update Agent
-//! - Genesis must be correct:
-//!     - Explicitly check action seqs 0, 1, and 2.
-//! - There can only be one InitZomesCompleted
-//! - All backlinks are in-chain (prev action, etc.)
-//!
+// TODO Add tests for:
+// - Create and Update Agent can only be preceded by AgentValidationPkg
+// - Author must match the entry hash of the most recent Create/Update Agent
+// - Genesis must be correct:
+//     - Explicitly check action seqs 0, 1, and 2.
+// - There can only be one InitZomesCompleted
+// - All backlinks are in-chain (prev action, etc.)
+//
+// TODO This "The DNA action can only be validated if the chain is empty" thing is a bit weird,
+//  refactor to not look in the db
 
 use super::*;
 use crate::conductor::space::TestSpaces;
diff --git a/crates/kitsune_p2p/dht/src/test_utils/op_data.rs b/crates/kitsune_p2p/dht/src/test_utils/op_data.rs
index c9ec934104..91e7daef2a 100644
--- a/crates/kitsune_p2p/dht/src/test_utils/op_data.rs
+++ b/crates/kitsune_p2p/dht/src/test_utils/op_data.rs
@@ -4,7 +4,7 @@ use kitsune_p2p_timestamp::Timestamp;
 
 use crate::{hash::OpHash, prelude::OpRegion, region::RegionData, Loc};
 
-/// TODO: mark this as for testing only.
+// TODO: mark this as for testing only.
 /// This is indeed the type that Holochain provides.
 #[derive(Clone, Debug, Hash, PartialEq, Eq)]
 pub struct OpData {
diff --git a/crates/kitsune_p2p/dht/tests/common/quantized.rs b/crates/kitsune_p2p/dht/tests/common/quantized.rs
index 0f8ccf0a8f..d1c96ccec8 100644
--- a/crates/kitsune_p2p/dht/tests/common/quantized.rs
+++ b/crates/kitsune_p2p/dht/tests/common/quantized.rs
@@ -57,8 +57,8 @@ where
 }
 
 /// Run iterations until there is no movement of any arc
-/// TODO: this may be unreasonable, and we may need to just ensure that arcs
-/// settle down into a reasonable level of oscillation
+// TODO: this may be unreasonable, and we may need to just ensure that arcs
+// settle down into a reasonable level of oscillation
 pub fn seek_convergence<F>(peers: Peers, step: F) -> Run
 where
     F: Fn(Peers) -> (Peers, EpochStats),
diff --git a/crates/kitsune_p2p/kitsune_p2p/src/test_util/scenario_def_local.rs b/crates/kitsune_p2p/kitsune_p2p/src/test_util/scenario_def_local.rs
index 2aa530adb2..d9a3846aee 100644
--- a/crates/kitsune_p2p/kitsune_p2p/src/test_util/scenario_def_local.rs
+++ b/crates/kitsune_p2p/kitsune_p2p/src/test_util/scenario_def_local.rs
@@ -19,7 +19,7 @@ use std::sync::Arc;
 /// A bit of a historical note: this type was created before `ScenarioDef`, and
 /// if it were the other way around, perhaps this type wouldn't exist. But it's
 /// still nice how concise it is.
-/// TODO: can this somehow be unified with `ScenarioDef`?
+// TODO: can this somehow be unified with `ScenarioDef`?
 pub struct LocalScenarioDef {
     /// Total number of op hashes to be generated
     pub total_ops: usize,