Add doc(hidden) guideline

Author: dtolnay

src/checklist.md

@@ -37,6 +37,7 @@
     - authors, description, license, homepage, documentation, repository,
       readme, keywords, categories
   - [ ] Release notes document all significant changes ([C-RELNOTES])
+  - [ ] Rustdoc does not show unhelpful implementation details ([C-HIDDEN])
 - **Predictability** *(crate enables legible code that acts how it looks)*
   - [ ] Smart pointers do not add inherent methods ([C-SMART-PTR])
   - [ ] Conversions live on the most specific type involved ([C-CONV-SPECIFIC])
@@ -103,6 +104,7 @@
 [C-LINK]: documentation.html#c-link
 [C-METADATA]: documentation.html#c-metadata
 [C-RELNOTES]: documentation.html#c-relnotes
+[C-HIDDEN]: documentation.html#c-hidden
 
 [C-SMART-PTR]: predictability.html#c-smart-ptr
 [C-CONV-SPECIFIC]: predictability.html#c-conv-specific

src/documentation.md

@@ -236,3 +236,33 @@ git push --tags
 - [Serde 0.9.8 release notes](https://github.com/serde-rs/serde/releases/tag/v0.9.8)
 - [Serde 0.9.0 release notes](https://github.com/serde-rs/serde/releases/tag/v0.9.0)
 - [Diesel change log](https://github.com/diesel-rs/diesel/blob/master/CHANGELOG.md)
+
+
+<a id="c-hidden"></a>
+## Rustdoc does not show unhelpful implementation details (C-HIDDEN)
+
+Rustdoc is supposed to include everything users need to use the crate fully and
+nothing more. It is fine to explain relevant implementation details in prose but
+they should not be real entries in the documentation.
+
+Especially be selective about which impls are visible in rustdoc -- all the ones
+that users would need for using the crate fully, but no others. In the following
+code the rustdoc of `PublicError` by default would show the `From<PrivateError>`
+impl. We choose to hide it with `#[doc(hidden)]` because users can never have a
+`PrivateError` in their code so this impl would never be relevant to them.
+
+```rust
+// This error type is returned to users.
+pub struct PublicError { /* ... */ }
+
+// This error type is returned by some private helper functions.
+struct PrivateError { /* ... */ }
+
+// Enable use of `?` operator.
+#[doc(hidden)]
+impl From<PrivateError> for PublicError {
+    fn from(err: PrivateError) -> PublicError {
+        /* ... */
+    }
+}
+```