I was about to send a post saying "phobos is mostly undocumented", by in the digitalmars site the documentation is pretty good for it. I was using Descent to see documentation for classes like Object, TypeInfo, etc., but in the source files provided with the DMD compiler some of the documentation is missing (inline). Is there a reason for this?

Ary Borenszweig wrote:
> I was about to send a post saying "phobos is mostly undocumented", by in the digitalmars site the documentation is pretty good for it. I was using Descent to see documentation for classes like Object, TypeInfo, etc., but in the source files provided with the DMD compiler some of the documentation is missing (inline). Is there a reason for this?

It looks like the documentation is generated from phobos/internal/object.d instead of phobos/object.d.

Maybe the ddocs were omitted from object.d because it's parsed for every module compiled, and stripping comments is wasted time?
Not that I think that's a good reason (it can't save much), but it's a possible reason...

Frits van Bommel escribió:
> Ary Borenszweig wrote:
>> I was about to send a post saying "phobos is mostly undocumented", by in the digitalmars site the documentation is pretty good for it. I was using Descent to see documentation for classes like Object, TypeInfo, etc., but in the source files provided with the DMD compiler some of the documentation is missing (inline). Is there a reason for this?
> 
> It looks like the documentation is generated from phobos/internal/object.d instead of phobos/object.d.
> 
> Maybe the ddocs were omitted from object.d because it's parsed for every module compiled, and stripping comments is wasted time?
> Not that I think that's a good reason (it can't save much), but it's a possible reason...

Ahh... that's a very good reason.

An alternative for missing documentation could be something like what Java does: it seems it has a standard documentation layout (directories and file names, as well as anchors in the HTML files). For example, in Eclipse JDT you can configure the javadoc location (local or external URL) of a jar or a bunch of classes, and, because this standard exists, it can show the documentation, even if it you don't have the source file of the classes.

Does such a "stanrdard" exist in D?

Ary Borenszweig wrote:
> An alternative for missing documentation could be something like what Java does: it seems it has a standard documentation layout (directories and file names, as well as anchors in the HTML files). For example, in Eclipse JDT you can configure the javadoc location (local or external URL) of a jar or a bunch of classes, and, because this standard exists, it can show the documentation, even if it you don't have the source file of the classes.
> 
> Does such a "stanrdard" exist in D?

Or we could do it the .NET way: Generate an XML file with DDoc comments   and make Descent read that file.


--
Julio César Carrascal Urquijo
http://jcesar.artelogico.com/