[Tracking Issue] Docs Enhancement: Documentation lacking API features.

[jaoleal]

The Floresta project has some deficiencies about code documentation and heres two of them:

Wrong imports (Good First Issue).

cargo docs sometimes doesnt know which components to show in a module/crate page because we didnt export them explicitly.

Example from: #375

This can happen

reading carefully the module, you'll notice that sync_node.rs and chain_selector are missing.

Adding

diff --git a/crates/floresta-wire/src/lib.rs b/crates/floresta-wire/src/lib.rs
index d6982f2..3452718 100644
--- a/crates/floresta-wire/src/lib.rs
+++ b/crates/floresta-wire/src/lib.rs
@@ -17,6 +17,7 @@ use bitcoin::Block;
 use bitcoin::Transaction;
 #[cfg(not(target_arch = "wasm32"))]
 pub use p2p_wire::address_man;
+pub use p2p_wire::chain_selector;
 #[cfg(not(target_arch = "wasm32"))]
 pub use p2p_wire::mempool;
 #[cfg(not(target_arch = "wasm32"))]
@@ -27,6 +28,7 @@ pub use p2p_wire::node_context;
 pub use p2p_wire::node_interface;
 #[cfg(not(target_arch = "wasm32"))]
 pub use p2p_wire::running_node;
+pub use p2p_wire::sync_node;
 pub use p2p_wire::UtreexoNodeConfig;
 /// NodeHooks is a trait that defines the hooks that a node can use to interact with the network
 /// and the blockchain. Every time an event happens, the node will call the corresponding hook.

Will expose the modules to cargo docs and make them appear on the crate documentation "home-page".

See #375

Modules Lacking Documentation.

Right in the example there's a module like running_node.rs that doesn't have any documentation shown and in its code we have some so, by adding:

diff --git a/crates/floresta-wire/src/p2p_wire/running_node.rs b/crates/floresta-wire/src/p2p_wire/running_node.rs
index 8c90265..e73e413 100644
--- a/crates/floresta-wire/src/p2p_wire/running_node.rs
+++ b/crates/floresta-wire/src/p2p_wire/running_node.rs
@@ -1,6 +1,6 @@
-/// After a node catches-up with the network, we can start listening for new blocks, handing any
-/// request our user might make and keep our peers alive. This mode requires way less bandwidth and
-/// CPU to run, being bound by the number of blocks found in a given period.
+//! After a node catches-up with the network, we can start listening for new blocks, handing any
+//! request our user might make and keep our peers alive. This mode requires way less bandwidth and
+//! CPU to run, being bound by the number of blocks found in a given period.
 use std::collections::BTreeMap;
 use std::collections::HashMap;
 use std::net::IpAddr;

will make the docs appear on the floresta-wire "home-page".

Note the changes from the earlier example applied here too.

How to close this issue

Tiny and Precise PRs like #375

• Encountering Modules that arent declarated in its crates.
• Documenting Modules that leaks documentation.

Note: Module documentation needs only to express the point of the module, but changes can be requested. like #375
Note: Some methods and types leaks documentation too, so it would be nice to have them documented as soon.

[moisesPompilio]

Hi, can I try this?

[jaoleal]

Hi, @moisesPompilio! Yes.

[lucad70]

Is it best to make a huge PR fixing everything or smaller PRs? And, if it be a huge PR, is it better to open a draft so the reviewers can check as it goes?

Also, did you mean lacking instead of leaking? @jaoleal

[lucad70]

Maybe we could "divide and conquer" @moisesPompilio . Like, we divide the crates between ourselves and then open two PRs without conflicting to avoid rework and speed up things... we have a lot of ground to cover. What do you think?

[qlrd]

Is it best to make a huge PR fixing everything or smaller PRs?

@lucad70, see CONTRIBUTING.md/commits. At the end (when PR is merged/closed), i think @Davidson-Souza will join them.

[jaoleal]

Is it best to make a huge PR fixing everything or smaller PRs? And, if it be a huge PR, is it better to open a draft so the reviewers can check as it goes?

@lucad70, tiny ones... Look #375, for example. Ill not be surprised if this issue, after completed, produces more than 10_000 lines of changes... Its unpractical to review all this at once in a single PR 🤓 .

I referenced #375 as a example(edited after @lucad70 comment) because this type of changes raise some old decisions inside this project that doesnt make sense anymore... And it happened on #375.

Also, did you mean lacking instead of leaking?

Yes, thank you.

[lucad70]

Got it! Thanks. I'll be working on it 👍🏼