View mode: basic / threaded / horizontal-split · Log in · Help
February 09, 2008
Phobos documentation in source files
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?
February 09, 2008
Re: Phobos documentation in source files
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...
February 09, 2008
Re: Phobos documentation in source files
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?
February 09, 2008
Re: Phobos documentation in source files
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/
Top | Discussion index | About this forum | D home