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?

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.

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!

Ary Borenszweig wrote:
>>> 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.

Might be a good idea for a feature request, some semantics would be really useful in the docs, as you said.

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

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.

On Sat, 04 Jul 2009 12:35:38 -0400, Ary Borenszweig <ary@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