Standardization of Rust Docs

[plebhash]

Proposals on standardization of formatting the comments for Rust Docs

[rrybarczyk]

Naming Conventions

Use clear and descriptive names for modules, functions, variables, and types. Follow Rust's naming conventions:

• Modules: snake_case
• Types and Traits: CamelCase
• Functions and Variables: snake_case
• Constants and Statics: SCREAMING_SNAKE_CASE

Functions/methods:

/// This is a short description of the function.
/// 
/// Optional longer notes/dev notes. This block should be separated by one new line from the short description above.
/// 
/// # Arguments
/// * `arg_0`: This is a short description of the first argument of the function.
/// * `arg_1`: This is a short description of the first argument of the function.
/// 
/// # Returns
/// This is a description of the return type of the function on success and on error. This should include what could cause an error as well. It should be separated by one new line from the arguments section, or if no arguments, from the description. If no return type, do not include this section.
fn my_function(arg_0: u8, arg_1: &str) -> Result<()> {
  // Function implementation here
}

Top level module

//! # Short Module Title
//!
//! This is a description of the purpose of the module. (Probably need more standards here, just kicking off the convo).

Structs

Note that each member field is separated by a new line. Do we like this?

/// Short description of purpose.
///
/// Optional longer description/notes/dev notes. This should be separated by one new line from the short description of the struct.
struct MyStruct {
  /// Short description of field. If the field is very obvious, can exclude any comments.
  ///
  /// Optional longer description/notes/dev notes. This should be separated by one new line from the short description of the member field.
  field_0: u8,

  field_1: &str,  // Assume this is an obvious field, so no comments needed.

  /// Short description.
  field_3: CustomStruct,
}

[jbesraa]

I am also not a big fan of the args/return in docs. When something unique or unusual in the args/ret or different error flows, it can be mentioned, otherwise, I agree with above comment that it feels redundant.

Regarding doc tests im on the fence. I would prefer to maintain unit tests plus integration tests to make sure all is working, and have a strong requirement for testing when reviewing PR. If we dont do that, I can see how doc tests can be useful.

[rrybarczyk]

Ok, then let's ditch the args/return. And I like the doc test idea a lot.

Something like this instead?

/// This is a short description of the function.
/// 
/// Optional longer notes/dev notes. This block should be separated by one new line from the short description above.
///
/// # Example (this is optional)
/// ```rust
/// use my_crate::my_function;
/// let result = my_function(0, "arg1");
/// assert!(result.is_ok());
/// ```
fn my_function(arg_0: u8, arg_1: &str) -> Result<()> {
  // Function implementation here
}

[rrybarczyk]

What about a doc test in the docs of the top of a module, overkill?

//! # Short Module Title
//!
//! This is a description of the purpose of the module.
//!
//! ## Example
//!
//! ```
//! use my_crate::add;
//! 
//! let result = add(2, 3);
//! assert_eq!(result, 5);
//! ```

[Shourya742]

Doc test can only be added to public facing modules. Makes sense to have them.

[rrybarczyk]

Agree. Let's be sure to have an example on the top of every module (or at least where it makes sense). Then we will not have examples anywhere else in the code (unless there is a specific need).

[rrybarczyk]

Added the Naming Conventions in the main discussion comment.

[rrybarczyk]

Also, we can use attributes for documentation if there is docs that are getting too verbose. #[doc(include = "path/to/file.md")] allows for the ability to include an external file in the documentation.

[rrybarczyk]

I would like to also add that wherever possible, use the cargo doc supported type linking syntax to make the datatypes used in the crates clickable, routing you to that type's definition.

For example, consider writing Rust docs in thenoise_sv2::initiator module, we can use the following syntax to achieve clickable reference links:

/// By adding the brackets and back ticks around the [`Initiator`] struct, this word/type generated
/// in the cargo docs will be clickable, taking you directly to that type definition.
///
/// Since the `initiator` module imports `aes_gcm::KeyInit`, I can also simply reference this type
/// with [`KeyInit`], and it will take me to its definition in the `aes_gcm` crate docs.
///
/// If I need to reference a data type in the `initiator` docs that is not directly used in the
/// module, then I can reference it by giving the docs the full crate path as [`crate::Responder`]
/// or [`crate::aed_cipher::AeadCipher`]. These will not become a clickable reference link to these
/// types.

[rrybarczyk]

Please let me know if everyone agrees and I will move this to the main comment in this discussion to be a guideline.

[Fi3]

ack

[jbesraa]

Strong ack. Here is a nice example from rust-lightning https://github.com/lightningdevkit/rust-lightning/blob/main/lightning/src/offers/nonce.rs#L21

[plebhash]

module visibility

a quote from @Fi3 :

if a module is private, we don't have to document it for user but for maintainers.

a rule of thumb is, if you think that you need to document a private module for the user, maybe the module should not be private

if the module (or struct, enum, fn, type, etc) is private and we still want to document it for maintainer eyes, we should use Non Doc comments, which are essentially // inlines and /* ... */ blocks

Non Doc comments are not rendered via cargo doc commands