Rustdoc should not silently discard documentation comments.

[orenbenkiki]

In general, no documentation comment should be discarded. Until this is the case, a discarded documentation comment should trigger a warning about an unsupported feature so the programmer would know the content wouldn't appear in the generated documentation.

Some examples of discarded documentation comments are impls:

/// Description of a foo...
pub struct Foo { ... }

/// Functions that bar the foo... - this comment is silently discarded by rustdoc.
impl Foo { pub fn bar(&self) { ... } }

/// Functions that baz the foo... - this comment is silently discarded by rustdoc.
impl Foo { pub fn baz(&self) { ... } }

Struct members:

pub struct Foo {
    /// Bar field... - this comment is silently discarded by rustdoc.
    bar: Bar,
}

Enum constructors:

pub enum Foo {
    /// Bar constructor... - this comment is silently discarded by rustdoc.
    Bar,
}

And there are probably others. Omitting such comments from the output reduces the usefulness of the documentation; doing so silently means the programmer can't tell when his documentation is being discarded.