[Gs-devel] Summary of procedure commenting discussion (re ANSIfication)

L. Peter Deutsch ghost at aladdin.com
Tue Nov 6 15:50:47 PST 2001


* Re documentation format standards:

Two people (Ralph and Gabriel) have said they like doxygen,

> 	http://www.stack.nl/~dimitri/doxygen/

Ralph observed about doxygen:

> I don't think there's a real standard here, though the javadoc comment
> format seems to be emerging as a common base. Of what's been suggested, I
> like DOxygen. It's pretty widely used (Mozilla and QT (with a difference
> comment format) and CrystalSpace are some other large projects) and it
> seems sane. My major reservation is that it doesn't seem to do docbook,
> which is what we want to use for the rest docs.The gtk/gnome tools do.

Two people (Peter and Stefan) like javadoc,

>  http://java.sun.com/j2se/javadoc/index.html

However, Stefan says:

> Sorry, my javadoc tool will not work.  We use c++ keywords, private in
> particular this gives tools that don't include a C preprocessor trouble.

Two people (Raph and Ralph) like gtk-doc format, from the gtk-doc-0.7
package available from

>  ftp://ftp.gtk.org/pub/gtk/v1.1/docs/rdp

My reading is that there is no consensus, and that if Ghostscript is going
to adopt a common commenting style for procedures, further discussion and
possibly experimentation will be required.

My conclusion for the ANSIfication project is that real procedure commenting
should NOT be included.

* Re commenting of prototypes and definitions:

Peter, Stefan, and Luke all agree that for both public procedure prototypes
in .h files and private procedure prototypes in .c files, the prototype
should include canonical names for the parameters, e.g.,

	int foo(int start, int stop);

The only other person who commented on this point was Igor, who didn't
object to this.

Those who offered an opinion said that interspersed comments like

>                 int     /* 0 for success, <0 for error */
>                 foo(
>                         int start,    /* starting position in string */
>                         int stop      /* ending position in string +1 */
>                 );

were *not* desirable, and that if the type and variable names weren't
self-explanatory enough, the documentation should be placed in a separate
block before the procedure prototype or definition.  This is my preference
too.  The above form was, I think, only used by John Desrosiers, a
consultant who is (as far as I know) no longer actively working on the main
Ghostscript code base.

My conclusion is that ANSIfication should include adding canonical parameter
names where they are currently missing, but should not attempt to add
further commenting.

The reason I care is that occasionally I have a restless night and want to
be able to do a bit of ANSIfication while I'm waiting to fall asleep again,
rather than counting sheep; and things would go even faster if others could
do the same with the assurance that we were all doing it the same way.

Further comments?

-- 

L. Peter Deutsch     |    Aladdin Enterprises   |  203 Santa Margarita Ave.
ghost at aladdin.com    |  http://www.aladdin.com  |  Menlo Park, CA 94025

	The future of software is at http://www.opensource.org



More information about the gs-devel mailing list