www.digitalmars.com         C & C++   DMDScript  

digitalmars.D - Phobos documentation in source files

reply Ary Borenszweig <ary esperanto.org.ar> writes:
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?
Feb 08 2008
parent reply Frits van Bommel <fvbommel REMwOVExCAPSs.nl> writes:
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...
Feb 08 2008
parent reply Ary Borenszweig <ary esperanto.org.ar> writes:
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?
Feb 08 2008
parent =?UTF-8?B?SnVsaW8gQ8Opc2FyIENhcnJhc2NhbCBVcnF1aWpv?= writes:
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/
Feb 08 2008