Repository navigation
RFCs 505 and 1574 contain contradictory information about method documentation #3784
Description
In both RFCs, you can find the following phrase:
The summary line should be written in third person singular present indicative form. Basically, this means write "Returns" instead of "Return".
However, the only example given in the two RFCs is
// Wait for the main task to return, and set the process error code
// appropriately.
Personally I prefer third person. The examples should be amended.
Reacted by Samuel Tardieu
Reacted by kennytm
Activity
bjorn3 commentedon Mar 10, 2025
RFC's are a snapshot in time and not meant to be updated after the fact. If you want this documented, it should be documented in one of the places where living documentation lives like https://rust-lang.github.io/api-guidelines/documentation.html, https://doc.rust-lang.org/rustdoc/how-to-write-documentation.html or https://doc.rust-lang.org/book/ch14-02-publishing-to-crates-io.html#making-useful-documentation-comments.
vigna commentedon Mar 10, 2025
I see. But that specific issue is only addressed there. I guess I can try a PR for a new item in one of those docs.