Thread overview | |||||
---|---|---|---|---|---|
|
December 03, 2017 Ddoc - No Documentation | ||||
---|---|---|---|---|
| ||||
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 |
December 02, 2017 Re: Ddoc - No Documentation | ||||
---|---|---|---|---|
| ||||
Posted in reply to Tony | 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
|
December 03, 2017 Re: Ddoc - No Documentation | ||||
---|---|---|---|---|
| ||||
Posted in reply to Jonathan M Davis | 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.
|
Copyright © 1999-2021 by the D Language Foundation