From cbf97c3e65e288702ccaea7f4a7153a37f7e4ee3 Mon Sep 17 00:00:00 2001 From: Martin Pool Date: Tue, 6 Oct 2015 19:42:58 -0700 Subject: [PATCH] style guide: suggest manual links to constructors --- src/doc/style/style/comments.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/src/doc/style/style/comments.md b/src/doc/style/style/comments.md index b2d2d9ab6b4..3851187b520 100644 --- a/src/doc/style/style/comments.md +++ b/src/doc/style/style/comments.md @@ -85,3 +85,20 @@ Use inner doc comments _only_ to document crates and file-level modules: //! //! The core library is a something something... ``` + +### Explain context. + +Rust doesn't have special constructors, only functions that return new +instances. These aren't visible in the automatically generated documentation +for a type, so you should specifically link to them: + +``` rust +/// An iterator that yields `None` forever after the underlying iterator +/// yields `None` once. +/// +/// These can be created through +/// [`iter.fuse()`](trait.Iterator.html#method.fuse). +pub struct Fuse { + // ... +} +```