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