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.
