When I have a method, should the first line of the documentation comment be a summary, or can I also directly start writing a long text? I assume the following is bad style?
/// This is `Foo`
///
/// Some longer text goes here.
trait Foo {
/// Should this have a headline, or can I directly write a lot of text here
/// because there is no overview on all of `Foo`'s methods, so it's not a
/// problem if this text is looooooooong.
fn foo(&self);
}
It is recommended to start with a summary as rustdoc will show the first line in places where only a single line fits like in module docs.
But this currently this isn't the case for methods, right? I think rustfmt currently doesn't create an overview where there is only one line shown. (But I guess it could exist in future.)
Oh, I'm wrong. When I do a search, for example, it will only show one line.
There are many recommendations and best practices here: How to write documentation - The rustdoc book
I saw that, but I wasn't sure if it would apply to every level (module, type, method, field, etc.), but apparently it does.
This topic was automatically closed 90 days after the last reply. We invite you to open a new topic if you have further questions or comments.