Cross-references in ddoc

Steven Schveighoffer schveiguy at yahoo.com
Tue Jul 7 11:23:21 PDT 2009


On Sat, 04 Jul 2009 12:35:38 -0400, Ary Borenszweig <ary at esperanto.org.ar>  
wrote:

> 1. (minor problem) Why isn't this appearing in the documentation?

Probably not documented (ddoc and dil only document when it sees the  
document tag, e.g. /*** or ///)

> 2. (major problem) How do you expect users to use your code if they  
> can't know what a given method accepts, or what that type is, or how to  
> find where a type that's returned by a function is defined?

Yeah, ddoc sucks.  I've gotten used to mostly ignoring the generated docs  
and looking at the source for info (for the most part).  The biggest  
problem is not having inherited documentation, especially for a large  
class tree like Tango.

> Documentation is *really* important when programming.
>
> 3. Is this a limitation in ddoc?

Yes

> 4. Is there a tool to generate documentation with cross-references?

Not for D.

> 5. Would it help if Descent generated cross-referenced documentation for  
> a project?

Yes.  I'd say if I had to rate features that would make me switch IDE's  
(or in my case, start using an IDE), this would be #1.  In fact, I think  
this feature would be a huge step in getting D into mainstream use.  Who  
wants to use an awesome language if you can't figure out how to use its  
libs?

Case in point, I bought a Java in a nutshell book, because I always liked  
the "in a nutshell series", but I don't think I've ever opened it, because  
javadoc is so much easier to use.  I didn't even bother with buying the C#  
nutshell book :)

-Steve


More information about the Digitalmars-d-learn mailing list