introducing writing documentation

added front page sample

component documentation

Added reference and include chapters

Author: AndyGauge

src/doc/rustdoc/src/SUMMARY.md

@@ -2,10 +2,12 @@
 
 - [What is rustdoc?](what-is-rustdoc.md)
 - [How to write documentation](how-to-write-documentation.md)
+- [What to include (and exclude)](what-to-include.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)
 - [Advanced Features](advanced-features.md)
 - [Unstable features](unstable-features.md)
+- [References](references.md)

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

@@ -1,14 +1,85 @@
 # How to write documentation
 
+Good documentation is not natural.  There are opposing forces that make good
+documentation difficult.  It requires expertise in the subject but also
+requires writing to a novice perspective.  Documentation therefore often 
+glazes over implementation detail, or leaves an explain like I'm 5 response.
+
+There are tenants to Rust documentation that can help guide anyone through
+the process of documenting libraries so everyone has ample opportunity to
+use the code.  
+
 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
+how to write **good** documentation.  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
+## Getting Started
+
+Documenting a crate should begin with front-page documentation.  As an
+example, [hashbrown] crate level documentation summarizes the role of
+the crate, provides links to explain technical details, and gives the 
+reason why to use the crate.  
+
+After introducing the crate, it is important that within the front-page 
+an example be given how to use the crate in a real world setting.  The
+example benefits from isolating the library's role from the implementation
+details, but doing so without shortcuts also benefits users who may copy
+and paste the example to get started. 
+
+[futures] uses an approach of inline comments to explain line by line
+the complexities of using a future, because often people's first exposure to 
+rust's future is this example.
+
+[backtrace] usage walks through the whole process, explaining changes made
+to the `Cargo.toml` file, passing command line arguments to the compiler,
+and shows a quick example of backtrace in the wild.  
+
+Finally, the front-page can eventually become a comprehensive reference
+how to ues a crate, like the usage found in [regex].  In this front page, all
+the requirements are outlined, the gotchas are taught, then practical examples
+are provided.  The front page goes on to show how to use regular expressions
+then concludes with crate features.
+
+Don't worry about comparing your crate that is just beginning to get
+documentation to something more polished, just start incrementally and put
+in an introduction, example, and features.  Rome wasn't built in a day!
+
+The first lines within the `lib.rs` will compose the front-page, and they
+use a different convention than the rest of the rustdocs.  Lines should
+start with `//!` which designate the code to refer to module-level or crate-
+level documentation.  Here's a quick example of the difference:
+
+```rust
+//! Fast and easy queue abstraction.
+//!
+//! Provides an abstraction over a queue.  When the abstraction is used
+//! there are these advantages:
+//! - Fast
+//! - [`Easy`]
+//!
+//! [`Easy`]: http://thatwaseasy.example.com
+
+/// This module makes it easy.
+pub mod easy {
+
+    /// Use the abstract function to do this specific thing.
+    pub fn abstract {}
+
+}
+```
+
+Ideally, this first line of documentation is a sentence without highly 
+technical details, but very broadly descriptive of where this crate fits
+within the rust ecosystem.  Someone should know if this crate is qualified
+for investigation in their use case by this line.
+
+## Documenting components
+
+Whether documenting modules, structs, functions, or macros, the public
+API of all code should have some documentation, and rarely does anyone
+complain about too much documentation.
 
 It is recommended that each item's documentation follows this basic structure:
 
@@ -23,9 +94,9 @@ It is recommended that each item's documentation follows this basic structure:
 ```
 
 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.
+documentation; while you might think that a code example is trivial,
+the examples are really important because they can help users 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:
@@ -62,6 +133,19 @@ for argument in env::args() {
 [`args_os`]: ./fn.args_os.html
 ``````
 
+The first line of description will be reused when describing the component in
+a higher level of the documentation.  For example, the function `std::env::args()`
+above can be found within the [`std::env`] module documentation.
+
+Because the type system does a good job of defining what is passed to a function
+and what is returned from one, there is not a benefit of explicitly writing those
+things into the documentation.  Rustdoc makes sure the links to the types included
+in the signature are linked.
+
+In the example above, a Panics section explains when the code might abruptly exit
+which can help the reader build guards if required.  A panic section is recommended
+every time edge cases in your code can be reached if known.
+
 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.
@@ -71,12 +155,16 @@ and finally provides a code example.
 `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
+[commonmark quick reference] is a very helpful resource for the majority of
+use cases.
 
-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
+[backtrace]: https://docs.rs/backtrace/0.3.50/backtrace/
 [commonmark markdown specification]: https://commonmark.org/
-[rustdoc-lints]: lints.md
+[commonmark quick reference]: https://commonmark.org/help/
+[env::args]: https://doc.rust-lang.org/stable/std/env/fn.args.html
+[futures]: https://docs.rs/futures/0.3.5/futures/
+[hashbrown]: https://docs.rs/hashbrown/0.8.2/hashbrown/
+[regex]: https://docs.rs/regex/1.3.9/regex/
+[standard library]: https://doc.rust-lang.org/stable/std/index.html
+[`std::env`]: https://doc.rust-lang.org/stable/std/env/index.html#functions

src/doc/rustdoc/src/references.md

@@ -0,0 +1,35 @@
+# References
+
+There are many great `rustdoc` references out there.  This is a collection of 
+those documentation documents on the internet at the time of writing.  If you
+know of other great resources, please submit a pull request:
+
+[Rust official Github]
+
+## Official 
+
+- [Learn Rust]
+- [Rust By Example]
+- [Rust Reference]
+- [RFC 1574: More API Documentation Conventions]
+- [RFC 1946: Intra Rustdoc Links]
+
+## Community 
+- [API Guidelines]
+- [Github tagged RFCs]
+- [Github tagged issues]
+- [RFC (stalled) front page styleguide]
+- [Guide on how to write documenation for a Rust crate]
+
+
+[API Guidelines]: https://rust-lang.github.io/api-guidelines/documentation.html
+[Github tagged RFCs]: https://github.com/rust-lang/rfcs/issues?q=label%3AT-rustdoc
+[Github tagged issues]: https://github.com/rust-lang/rust/issues?q=is%3Aissue+is%3Aopen+label%3AT-rustdoc
+[Guide on how to write documenation for a Rust crate]: https://blog.guillaume-gomez.fr/articles/2020-03-12+Guide+on+how+to+write+documentation+for+a+Rust+crate
+[Learn Rust]: https://doc.rust-lang.org/book/ch14-02-publishing-to-crates-io.html#making-useful-documentation-comments
+[RFC 1574: More API Documentation Conventions]: https://rust-lang.github.io/rfcs/1574-more-api-documentation-conventions.html
+[RFC 1946: Intra Rustdoc Links]: https://rust-lang.github.io/rfcs/1946-intra-rustdoc-links.html
+[RFC (stalled) front page styleguide]: https://github.com/rust-lang/rfcs/pull/1687
+[Rust By Example]: https://doc.rust-lang.org/stable/rust-by-example/meta/doc.html
+[Rust official Github]: https://github.com/rust-lang/rust/pulls
+[Rust Reference]: https://doc.rust-lang.org/stable/reference/comments.html#doc-comments

src/doc/rustdoc/src/what-is-rustdoc.md

@@ -32,7 +32,11 @@ $ rustdoc src/lib.rs
 This will create a new directory, `doc`, with a website inside! In our case,
 the main page is located in `doc/lib/index.html`. If you open that up in
 a web browser, you'll see a page with a search bar, and "Crate lib" at the
-top, with no contents. There's two problems with this: first, why does it
+top, with no contents. 
+
+## Configuring rustdoc
+
+There's two problems with this: first, why does it
 think that our package is named "lib"? Second, why does it not have any
 contents?
 
@@ -85,13 +89,12 @@ dependency=<path>/docs/target/debug/deps
 You can see this with `cargo doc --verbose`.
 
 It generates the correct `--crate-name` for us, as well as pointing to
-`src/lib.rs` But what about those other arguments? `-o` controls the
-*o*utput of our docs. Instead of a top-level `doc` directory, you'll
-notice that Cargo puts generated documentation under `target`. That's
-the idiomatic place for generated files in Cargo projects. Also, it
-passes `-L`, a flag that helps rustdoc find the dependencies
-your code relies on. If our project used dependencies, we'd get
-documentation for them as well!
+`src/lib.rs` But what about those other arguments? 
+ - `-o` controls the *o*utput of our docs. Instead of a top-level 
+ `doc` directory, notice that Cargo puts generated documentation under 
+ `target`. That is the idiomatic place for generated files in Cargo projects.
+ - `-L` flag helps rustdoc find the dependencies your code relies on. 
+ If our project used dependencies, we'd get documentation for them as well!
 
 ## Using standalone Markdown files
 
@@ -105,7 +108,7 @@ This is a project to test out `rustdoc`.
 
 [Here is a link!](https://www.rust-lang.org)
 
-## Subheading
+## Example
 
 ```rust
 fn foo() -> i32 {

src/doc/rustdoc/src/what-to-include.md

@@ -0,0 +1,119 @@
+# What to include (and exclude)
+
+It is easy to say everything must be documented in a project and often times
+that is correct, but how can we get there, and are there things that don't
+belong?
+
+At the top of the `src/lib.rs` or `main.rs` file in your binary project, include
+the following attribute:
+
+```rust
+#![warn(missing_docs)]
+```
+
+Now run `cargo doc` and examine the output.  Here's a sample:
+
+```text
+ Documenting docdemo v0.1.0 (/Users/username/docdemo)
+warning: missing documentation for the crate
+ --> src/main.rs:1:1
+  |
+1 | / #![warn(missing_docs)]
+2 | |
+3 | | fn main() {
+4 | |     println!("Hello, world!");
+5 | | }
+  | |_^
+  |
+note: the lint level is defined here
+ --> src/main.rs:1:9
+  |
+1 | #![warn(missing_docs)]
+  |         ^^^^^^^^^^^^
+
+warning: 1 warning emitted
+
+    Finished dev [unoptimized + debuginfo] target(s) in 2.96s
+```
+
+As a library author, adding the lint `#![deny(missing_docs)]` is a great way to
+ensure the project does not drift away from being documented well, and warn is
+a good way to move towards comprehensive documentation.
+
+In our example above, the warning is resolved by adding crate level
+documentation.  The `main` method does not need documentation, but it is 
+present in the output.  If your main method is doing anything special, like
+returning a `Result`, it could use documentation!
+
+```rust
+#![warn(missing_docs)]
+
+//! Run program to print Hello, world.
+
+/// Allows unhandled errors to become program return values
+fn main() -> std::io::Result<()> {
+    print_it();
+    Ok(())
+}
+
+/// Safely prints Hello, world!
+fn print_it() {
+    println!("Hello, world!");
+}
+```
+There are more lints in the upcoming chapter [Lints][rustdoc-lints].
+
+## Examples
+
+Of course this is contrived to be simple, but part of the power of documentation
+is showing code that is easy to follow, rather than being realistic.  Docs often
+shortcut error handling because often examples become complicated to follow
+with all the necessary set up required for a simple example.
+
+`Async` is a good example of this.  In order to execute an `async` example, an
+executor needs to be available.  Examples will often shortcut this, and leave
+users to figure out how to put the `async` code into their own runtime.
+
+It is preferred that `unwrap()` not be used inside an example, and some of the
+error handling components be hidden if they make the example too difficult to
+follow.  
+
+``````rust
+/// Example
+/// ```rust
+/// let fourtytwo = "42".parse::<u32>()?;
+/// println!("{} + 10 = {}", fourtytwo, fourtytwo+10);
+/// ```
+``````  
+
+When rustdoc wraps that in a main function, it will panic due to the 
+`ParseIntError` trait not implemented.  In order to help both your audience
+and your test suite, this example needs to have additional work performed:
+
+``````rust
+/// Example
+/// ```rust
+/// # main() -> Result<(), std::num::ParseIntError> {
+/// let fourtytwo = "42".parse::<u32>()?;
+/// println!("{} + 10 = {}", fourtytwo, fourtytwo+10);
+/// #     Ok(())
+/// # }
+/// ```
+``````  
+
+The example is the same on the doc page, but has that extra information
+available to anyone trying to use your crate.  More about tests in the 
+upcoming [Documentation tests] chapter.  
+
+## What to Exclude
+
+Certain parts of your public interface may be included by default in the output
+of rustdoc.  The attribute `#[doc(hidden)]` hides the non-public consumption
+implementation details to facilitate idiomatic Rust.  
+
+Good examples are `impl From<Error>` for providing `?` usage, or `impl Display`.
+
+
+
+[Documentation tests]: documentation-tests.md
+[rustdoc-lints]: lints.md