Cross-references in ddoc

[Jacob Carlborg]

On 7/4/09 6:35 PM, 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.
>
> 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?
> 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?
>
> Documentation is *really* important when programming.
>
> 3. Is this a limitation in ddoc?
> 4. Is there a tool to generate documentation with cross-references?
> 5. Would it help if Descent generated cross-referenced documentation for
> a project?

Dil seems to have macros to generate links to other parts of the 
documentation and every symbol in the tango documentation has an anchor 
link to itself (if you click the paragraph symbol).

Another nice thing would be to see the methods a subclass inherit from 
all it's superclass/interface.