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!
