Cross-references in ddoc

[Robert Clipsham]

Ary Borenszweig wrote:
> I've seen both Tango and phobos documentation and it's really hard to 
> navigate. Consider this:
> 
> class HttpPost {
> 
>   void[] write(Pump pump)
> 
> }
> 
> Pump has no link on it. I can't tell what Pump is. I can see the source 
> code (in the web page) invokes super.write(pump), or something like 
> that, so I go to HttpClient and there it's not defined.

Tangos docs are generated with dil, which currently has limited semantic 
analysis, so adding a link isn't possible yet. Once dil gets more 
semantic analysis I believe links will be added in.

> 
> I open Tango's source code and I find this:
> 
> alias void delegate (IBuffer) Pump;
> 
> So some questions:
> 
> 1. (minor problem) Why isn't this appearing in the documentation?

I'd like an answer to this too, it's a pain to have to look at the 
source code to find something simple like this.

> 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?

Don't the docs already give this? (Except where it's defined, which 
isn't possible due to the aforementioned reason)

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

It's a limitation in dil. dmd does not have the same limitations, 
however I've never needed to generate any docs so can't say much here.

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

dmd probably can do this, again I've never done it so don't know.

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

I'm sure someone would find it useful to be able to click a button to 
generate documentation rather than hit a terminal and enter a command.