www.digitalmars.com         C & C++   DMDScript  

digitalmars.D.learn - Ddoc - No Documentation

reply Tony <tonytdominguez aol.com> writes:
Wondering what the rationale is for this:

https://dlang.org/spec/ddoc.html#no_documentation

No Documentation

No documentation is generated for the following constructs, even 
if they have a documentation comment:

Invariants
Postblits
Destructors
Static constructors and static destructors
Class info, type info, and module info
Dec 02
parent reply Jonathan M Davis <newsgroup.d jmdavisprog.com> writes:
On Sunday, December 03, 2017 00:14:10 Tony via Digitalmars-d-learn wrote:
 Wondering what the rationale is for this:

 https://dlang.org/spec/ddoc.html#no_documentation

 No Documentation

 No documentation is generated for the following constructs, even
 if they have a documentation comment:

 Invariants
 Postblits
 Destructors
 Static constructors and static destructors
 Class info, type info, and module info
Presumably, because they are not things that you would ever explicitly use. The whole point of the documentation is to document what the types and functions being documented do and how to use them. If they're not something that you're going to explicitly use, then there really isn't anything to document. In general, the items you listed are just implementation details (e.g. a static constructor certainly isn't part of a public API), or they're something that exists for types in general, and there's nothing special to document (e.g. all classes have a corresponding TypeInfo; there's nothing about a specific class' TypeInfo that merits documentation, and it's not something that's actually explicitly in the module anyway; it's all generated by the compiler). - Jonathan M Davis
Dec 02
parent Adam D. Ruppe <destructionator gmail.com> writes:
On Sunday, 3 December 2017 at 00:25:34 UTC, Jonathan M Davis 
wrote:
 Presumably, because they are not things that you would ever 
 explicitly use. The whole point of the documentation is to 
 document what the types and functions being documented do and 
 how to use them. If they're not something that you're going to 
 explicitly use, then there really isn't anything to document.
Implicit use is important to understand what's going on too. My adrdox generator does document those... even if they don't have a comment, because just knowing they are there is valuable in understanding the type. So your explanation might be the reason, but I disagree with it and I doubt I'm the only one.
Dec 02