[Issue 3161] New: Ddoc should produce much better documentation

[d-bugmail at puremagic.com]

http://d.puremagic.com/issues/show_bug.cgi?id=3161

           Summary: Ddoc should produce much better documentation
           Product: D
           Version: unspecified
          Platform: All
        OS/Version: All
            Status: NEW
          Keywords: ddoc
          Severity: enhancement
          Priority: P3
         Component: DMD
        AssignedTo: nobody at puremagic.com
        ReportedBy: ary at esperanto.org.ar


Currently the documentation produced by ddoc is poor. It lacks many of the
features modern documetantion systems like the ones of Java and C# provide.
Some of these are:

1. Links to referenced symbols.
2. Supertype hierarchy of a class.
3. Direct known subclasses of a class.
4. Direct known subinterfaces of an interface.
5. All interfaces implemented by a class.
6. All classes that implement an interface.
7. Show documentation for symbols generated by mixins.
8. List of inherited methods.
9. Public imports exposed by a module.

If "1" is not present, the phrase "navigating the documentation" just doesn't
make sense.

2, 3, 4 and 5 allows you to quickly find a class that implements the
functionality you are looking for. Otherwise it's impossible to (easily) search
for implementations. Suppose you have an InputStream interface (like in Tango).
This would allow you to find a specific InputStream for your needs (for
example, where's the input stream to read a file, a socket, a string, etc.).

9 is also important because otherwise you have to look at the source code.

The other points are also important for me, because it gives you a better
overview of the symbols.

You can see an example of a documentation that works like this here:

phobos: http://downloads.dsource.org/projects/descent/ddoc/phobos/
Tango: http://downloads.dsource.org/projects/descent/ddoc/tango/

-- 
Configure issuemail: http://d.puremagic.com/issues/userprefs.cgi?tab=email
------- You are receiving this mail because: -------