Re: [AD] Makedoc patch (was: 4.0.x branch)

[Stepan Roh <stepan@xxxxxxxxxx>]

On Thu, 21 Feb 2002, Martijn Versteegh wrote:

> >
> >This clearly indicates bad documentation layout. See Javadoc's or
> >Doxygen's standard doclets how it should look like.

> I must say I don't like Doxygen documentation at all (or any other
> sourcecode driven system , that is). This is because doxygen organises
> the docs like the source, but the docs should be organised by logical
> 'association'.

That is the valid point. But that clearly indicates that your sources are
badly organised. Oh god, I'm too much Javaized. :-)

> This is more or less the way the allegro docs are. IMHO the allegro
> documentation is one of the best there is (except that is would be nice
> if the sections were in alphabetical order) . This has always been one
> of the strong points of allegro.

In the case with "This clearly indicates bad documentation layout. See
Javadoc's or Doxygen's standard doclets how it should look like." I meant
reorganizing of function descriptions. In that case look into Javadoc's or
Doxygen's doclets. Example follows (Javadoc pseudo-output):

---------------------------

java.lang
Class String

 java.lang.Object
   |
   +--java.lang.String

   All Implemented Interfaces:
           Comparable, Serializable

   ---------------------------------------------------------------------

   public final class String

   extends Object

   implements Serializable, Comparable

   The String class represents character strings. All string literals in
   Java programs, such as "abc", are implemented as instances of this class.
   ....

   Since:
           JDK1.0

   See Also:
           Object.toString(), StringBuffer, StringBuffer.append(boolean),
           ....

   ....

   Method Summary
   ....
   int compareTo(Object o)
                 Compares this String to another Object.
   ....

   ....

   Method Detail

   ---------------------------------------------------------------------
     compareTo

 public int compareTo(Object o)

           Compares this String to another Object. If the Object is a
           String, this function behaves like compareTo(String).
           Otherwise, it throws a ClassCastException (as Strings are
           comparable only
           to other Strings).

                Specified by:
                        compareTo in interface Comparable

                Parameters:
                        o - the Object to be compared.

                Returns:
                        the value 0 if the argument is a string
                        lexicographically equal to this string; a value
                        less than 0 if the argument is a string
                        lexicographically greater than this string; and a
                        value greater than 0 if the argument is a string
                        lexicographically less than this string.

                Throws:
                        ClassCastException - if the argument is not a String.

                Since:
                        1.2

                See Also:
                        Comparable

--------------------

Parameters description is one of the things which is missing in current
Allegro documentation as well as return statement. And it should be
clearly delimited from the rest.

Have a nice day.

Stepan Roh