Rollup merge of #66267 - GuillaumeGomez:add-rustdoc-doc, r=kinnison

Add rustdoc doc

r? @kinnison

src/doc/rustdoc/src/SUMMARY.md

@@ -1,8 +1,10 @@
 # The Rustdoc Book
 
 - [What is rustdoc?](what-is-rustdoc.md)
+- [How to write documentation](how-to-write-documentation.md)
 - [Command-line arguments](command-line-arguments.md)
 - [The `#[doc]` attribute](the-doc-attribute.md)
 - [Documentation tests](documentation-tests.md)
+- [Lints](lints.md)
 - [Passes](passes.md)
 - [Unstable features](unstable-features.md)

src/doc/rustdoc/src/how-to-write-documentation.md

@@ -0,0 +1,82 @@
+# How to write documentation
+
+This chapter covers not only how to write documentation but specifically
+how to write **good** documentation.  Something to keep in mind when
+writing documentation is that your audience is not just yourself but others
+who simply don't have the context you do.  It is important to be as clear
+as you can, and as complete as possible.  As a rule of thumb: the more
+documentation you write for your crate the better.  If an item is public
+then it should be documented.
+
+## Basic structure
+
+It is recommended that each item's documentation follows this basic structure:
+
+```text
+[short sentence explaining what it is]
+
+[more detailed explanation]
+
+[at least one code example that users can copy/paste to try it]
+
+[even more advanced explanations if necessary]
+```
+
+This basic structure should be straightforward to follow when writing your
+documentation and, while you might think that a code example is trivial,
+the examples are really important because they can help your users to
+understand what an item is, how it is used, and for what purpose it exists.
+
+Let's see an example coming from the [standard library] by taking a look at the
+[`std::env::args()`][env::args] function:
+
+``````text
+Returns the arguments which this program was started with (normally passed
+via the command line).
+
+The first element is traditionally the path of the executable, but it can be
+set to arbitrary text, and may not even exist. This means this property should
+not be relied upon for security purposes.
+
+On Unix systems shell usually expands unquoted arguments with glob patterns
+(such as `*` and `?`). On Windows this is not done, and such arguments are
+passed as-is.
+
+# Panics
+
+The returned iterator will panic during iteration if any argument to the
+process is not valid unicode. If this is not desired,
+use the [`args_os`] function instead.
+
+# Examples
+
+```
+use std::env;
+
+// Prints each argument on a separate line
+for argument in env::args() {
+    println!("{}", argument);
+}
+```
+
+[`args_os`]: ./fn.args_os.html
+``````
+
+As you can see, it follows the structure detailed above: it starts with a short
+sentence explaining what the functions does, then it provides more information
+and finally provides a code example.
+
+## Markdown
+
+`rustdoc` is using the [commonmark markdown specification]. You might be
+interested into taking a look at their website to see what's possible to do.
+
+## Lints
+
+To be sure that you didn't miss any item without documentation or code examples,
+you can take a look at the rustdoc lints [here][rustdoc-lints].
+
+[standard library]: https://doc.rust-lang.org/stable/std/index.html
+[env::args]: https://doc.rust-lang.org/stable/std/env/fn.args.html
+[commonmark markdown specification]: https://commonmark.org/
+[rustdoc-lints]: lints.md

src/doc/rustdoc/src/lints.md

@@ -0,0 +1,119 @@
+# Lints
+
+`rustdoc` provides lints to help you writing and testing your documentation. You
+can use them like any other lints by doing this:
+
+```rust,ignore
+#![allow(missing_docs)] // allowing the lint, no message
+#![warn(missing_docs)] // warn if there is missing docs
+#![deny(missing_docs)] // rustdoc will fail if there is missing docs
+```
+
+Here is the list of the lints provided by `rustdoc`:
+
+## intra_doc_link_resolution_failure
+
+This lint **warns by default** and is **nightly-only**. This lint detects when
+an intra-doc link fails to get resolved. For example:
+
+```rust
+/// I want to link to [`Inexistent`] but it doesn't exist!
+pub fn foo() {}
+```
+
+You'll get a warning saying:
+
+```text
+error: `[`Inexistent`]` cannot be resolved, ignoring it...
+```
+
+## missing_docs
+
+This lint is **allowed by default**. It detects items missing documentation.
+For example:
+
+```rust
+#![warn(missing_docs)]
+
+pub fn undocumented() {}
+# fn main() {}
+```
+
+The `undocumented` function will then have the following warning:
+
+```text
+warning: missing documentation for a function
+  --> your-crate/lib.rs:3:1
+   |
+ 3 | pub fn undocumented() {}
+   | ^^^^^^^^^^^^^^^^^^^^^
+```
+
+## missing_doc_code_examples
+
+This lint is **allowed by default**. It detects when a documentation block
+is missing a code example. For example:
+
+```rust
+#![warn(missing_doc_code_examples)]
+
+/// There is no code example!
+pub fn no_code_example() {}
+# fn main() {}
+```
+
+The `no_code_example` function will then have the following warning:
+
+```text
+warning: Missing code example in this documentation
+  --> your-crate/lib.rs:3:1
+   |
+LL | /// There is no code example!
+   | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+```
+
+To fix the lint, you need to add a code example into the documentation block:
+
+```rust
+/// There is no code example!
+///
+/// ```
+/// println!("calling no_code_example...");
+/// no_code_example();
+/// println!("we called no_code_example!");
+/// ```
+pub fn no_code_example() {}
+```
+
+## private_doc_tests
+
+This lint is **allowed by default**. It detects documentation tests when they
+are on a private item. For example:
+
+```rust
+#![warn(private_doc_tests)]
+
+mod foo {
+    /// private doc test
+    ///
+    /// ```
+    /// assert!(false);
+    /// ```
+    fn bar() {}
+}
+# fn main() {}
+```
+
+Which will give:
+
+```text
+warning: Documentation test in private item
+  --> your-crate/lib.rs:4:1
+   |
+ 4 | /     /// private doc test
+ 5 | |     ///
+ 6 | |     /// ```
+ 7 | |     /// assert!(false);
+ 8 | |     /// ```
+   | |___________^
+```