• Ary Borenszweig (20/20) Jul 04 2009 I've seen both Tango and phobos documentation and it's really hard to
• Robert Clipsham (13/42) Jul 04 2009 Tangos docs are generated with dil, which currently has limited semantic...
• Ary Borenszweig (9/60) Jul 04 2009 I mean, you can click on the type to see it's documentation. It would
• Robert Clipsham (3/20) Jul 04 2009 Might be a good idea for a feature request, some semantics would be
• Jacob Carlborg (6/26) Jul 05 2009 Dil seems to have macros to generate links to other parts of the
• Steven Schveighoffer (20/29) Jul 07 2009 Probably not documented (ddoc and dil only document when it sees the

Ary Borenszweig <ary esperanto.org.ar> writes:

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?

Robert Clipsham <robert octarineparrot.com> writes:

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.

Ary Borenszweig <ary esperanto.org.ar> writes:

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!

Robert Clipsham <robert octarineparrot.com> writes:

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!

Jacob Carlborg <doob me.com> writes:

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.

"Steven Schveighoffer" <schveiguy yahoo.com> writes:

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  

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  

nutshell book :)

-Steve