Cross-references in ddoc

Ary Borenszweig ary at esperanto.org.ar
Sat Jul 4 16:36:30 PDT 2009


Robert Clipsham escribió:
> 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)

I mean, you can click on the type to see it's documentation. It would 
also be nice if, if the type is an alias, show the alias resolution when 
hovering it.

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

No, it doesn't. I think it doesn't because semantic analysis isn't run 
when generating docs.

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

You are right. :)

I'll try to work on something...

Thanks for your answers, Robert!


More information about the Digitalmars-d-learn mailing list