Why is List(T) documented in std.concurrency?

[Jonathan M Davis]

On Wednesday, April 25, 2012 17:31:29 Ali Çehreli wrote:
> On 04/25/2012 02:15 PM, Jonathan M Davis wrote:
> > On Wednesday, April 25, 2012 22:01:45 Mirko Pilger wrote:
> >>> Since there's only one *, it shouldn't show up in the docs, even if it's
> >>> public.
> >> 
> >> "If there is no documentation comment for a declaration, that
> >> declaration may not appear in the output. To ensure it does appear in
> >> the output, put an empty declaration comment for it."
> >> 
> >> http://dlang.org/ddoc.html
> > 
> > Yes, but the comment on it is _not_ a ddoc comment. It's a regular
> > comment.
> > So, it shouldn't appear in the docs. For it to be a ddoc comment it would
> > need to start with /++ or /**, but it starts with /*.
> > 
> > - Jonathan Davis
> 
> But the documentation is vague enough to also mean that even without
> comments it may appear. :)
> 
> "... may not appear in the output. To ensure it does appear ..."

Yeah. That wording is pretty atrocious. There should be no ambiguity. But it 
is my understanding that if you don't have a ddoc comment on a symbol, it 
should _never_ end up in the documentation, and prior to this particular case, 
I've never seen it happen.

- Jonathan M Davis