Replies: 9 comments 27 replies
-
Naming ConventionsUse clear and descriptive names for modules, functions, variables, and types. Follow Rust's naming conventions:
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).
StructsNote 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,
} |
Beta Was this translation helpful? Give feedback.
-
|
Ok, then let's ditch the args/return. And I like the doc test idea a lot. Something like this instead? |
Beta Was this translation helpful? Give feedback.
-
|
What about a doc test in the docs of the top of a module, overkill? |
Beta Was this translation helpful? Give feedback.
-
|
Doc test can only be added to public facing modules. Makes sense to have them. |
Beta Was this translation helpful? Give feedback.
-
|
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). |
Beta Was this translation helpful? Give feedback.
-
|
while reviewing #1040 I noticed instances where the module headers were introducing a that is redundant since all types are already listed on Rust Docs automatically doing this is actually a potential footgun, because now whenever we introduce code changes we need to:
|
Beta Was this translation helpful? Give feedback.
-
|
Added the Naming Conventions in the main discussion comment. |
Beta Was this translation helpful? Give feedback.
-
|
Also, we can use attributes for documentation if there is docs that are getting too verbose. |
Beta Was this translation helpful? Give feedback.
-
|
I would like to also add that wherever possible, use the For example, consider writing Rust docs in the /// 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.
|
Beta Was this translation helpful? Give feedback.
-
|
Please let me know if everyone agrees and I will move this to the main comment in this discussion to be a guideline. |
Beta Was this translation helpful? Give feedback.
-
|
ack |
Beta Was this translation helpful? Give feedback.
-
|
Strong ack. Here is a nice example from rust-lightning https://github.com/lightningdevkit/rust-lightning/blob/main/lightning/src/offers/nonce.rs#L21 |
Beta Was this translation helpful? Give feedback.
-
module visibility
if the module (or Non Doc comments are not rendered via |
Beta Was this translation helpful? Give feedback.
-
examplesexamples showing how to use public APIs are always good: they allow the reader to get a quick understanding of how the APIs should be used without having to read through the description of every single element we might want to write an example showing how to use a small examples (few lines of code) should be written as doc tests if the example is big, we should:
examples should only cover public APIs |
Beta Was this translation helpful? Give feedback.
-
|
What do you all think of the syntax and verbage in these comments in the // # Using Sv2 Codec with Noise Encryption
//
// This example demonstrates how to use the `codec-sv2` crate to encode and decode Sv2 frames
// with Noise protocol encryption over a TCP connection. It showcases how to:
//
// * Perform a Noise handshake between the sender and receiver.
// * Create an arbitrary custom message type (`CustomMessage`) for encryption/encoding and
// decryption/decoding.
// * Encode the message into an encrypted Sv2 frame using Noise.
// * Send the encrypted frame over a TCP connection.
// * Decode the encrypted Sv2 frame on the receiving side after completing the Noise handshake.
//
// ## Run
//
// ```
// cargo run --example encrypted --features noise_sv2
// ``` |
Beta Was this translation helpful? Give feedback.
-
README.mdlet's try to follow the format below: |
Beta Was this translation helpful? Give feedback.
-
|
|
Beta Was this translation helpful? Give feedback.
-
|
one important detail to take into consideration:
|
Beta Was this translation helpful? Give feedback.
-
|
I am loving @GitGab19's Thoughts:
|
Beta Was this translation helpful? Give feedback.
-
|
yeah if the crate has an |
Beta Was this translation helpful? Give feedback.
-
FFI
every time we update Rust Docs on some crate that is covered by therefore we should also update a new updated one might object: "a Rust Docs PR should not touch any crates other than the one being documented" I believe this is an exception, since these changes are atomically linked and therefore deserve to belong to the same PR it should suffice to add a note to the PR description highlighting that |
Beta Was this translation helpful? Give feedback.
-
crate versioningthe main point of writing the Rust Docs is to have them publicly displayed, so we need to publish those crates to
for it was pointed out on #1222 that we should probably start bumping PATCH instead |
Beta Was this translation helpful? Give feedback.
-
|
https://doc.rust-lang.org/cargo/reference/resolver.html |
Beta Was this translation helpful? Give feedback.
-
|
Beta Was this translation helpful? Give feedback.
-
|
I don't think there would be any particular problem with bumping MINOR, but I'm totally fine with bumping the PATCH in this case 👍 |
Beta Was this translation helpful? Give feedback.
-
|
If you bump minor with no API changes you are not following semver this should be enough for not doing it. But below a pratical example where this would be an issue: let's say that you bump minor for A and you have 1.1.0 and 1.2.0 |
Beta Was this translation helpful? Give feedback.
-
|
Got it. So let's bump PATCH when we document crates 👍 |
Beta Was this translation helpful? Give feedback.
-
Proposals on standardization of formatting the comments for Rust Docs
Beta Was this translation helpful? Give feedback.
All reactions