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.
