www.digitalmars.com         C & C++   DMDScript  

digitalmars.D.learn - Cross-references in ddoc

reply 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?
Jul 04 2009
next sibling parent reply 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.
Jul 04 2009
parent reply 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!
Jul 04 2009
parent 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!
Jul 04 2009
prev sibling next sibling parent 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.
Jul 05 2009
prev sibling parent "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 (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
Jul 07 2009