www.digitalmars.com         C & C++   DMDScript  

digitalmars.D.learn - Why is List(T) documented in std.concurrency?

reply =?ISO-8859-1?Q?Alex_R=F8nne_Petersen?= <xtzgzorex gmail.com> writes:
Hi,

http://dlang.org/phobos/std_concurrency.html

Why does List(T) appear? Isn't it private?

-- 
- Alex
Apr 25 2012
parent reply "Jonathan M Davis" <jmdavisProg gmx.com> writes:
On Wednesday, April 25, 2012 21:00:33 Alex Rønne Petersen wrote:

 Hi,
 
 http://dlang.org/phobos/std_concurrency.html
 
 Why does List(T) appear? Isn't it private?


It's probably due to http://d.puremagic.com/issues/show_bug.cgi?id=2775

However, to make things weirder, it _doesn't_ have ddoc on it. It's

 /*
 *
 */
 struct List(T)

Since there's only one *, it shouldn't show up in the docs, even if it's 
public. So, there may actually be another bug relating to nested structs and 
ddoc which combines with 2775 to make List appear in the docs.

- Jonathan M Davis
Apr 25 2012
parent reply Mirko Pilger <pilger cymotec.de> writes:
 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
Apr 25 2012
parent reply "Jonathan M Davis" <jmdavisProg gmx.com> writes:
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
Apr 25 2012
parent reply =?UTF-8?B?QWxpIMOHZWhyZWxp?= <acehreli yahoo.com> writes:
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 ..."

Ali
Apr 25 2012
parent Jonathan M Davis <jmdavisProg gmx.com> writes:
On Wednesday, April 25, 2012 17:31:29 Ali =C3=87ehreli 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.


=20
 "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."
=20
 http://dlang.org/ddoc.html


=20
 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 /*.
=20
 - Jonathan Davis


=20
 But the documentation is vague enough to also mean that even without
 comments it may appear. :)
=20
 "... may not appear in the output. To ensure it does appear ..."


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

- Jonathan M Davis
Apr 25 2012