Re: GNOME -- status and future.

[Christian Leutloff <leutloff sundancer oche de>]

Miguel de Icaza <miguel@nuclecu.unam.mx> writes:

> * Documentation 
> ---------------
> 
>     Horacio has been working on the Gnome tutorial (on what is
> involved in making a Gnome application) and he is attempting to
> document the Gnome API.  
> 
> We want to embed the documentation on the source code and extract the
> documentation into the DocBook sgml with some kind of Perl script.  If
> anyone has specific suggestions on what to use, please, go ahead.  I
> have suggested something like:
> 
> 	/* 
> 	 * Function: gnomo_do
> 	 *
> 	 * Parameters:
> 	 *       GtkWidget *target
> 	 *       int       gnomo_action
> 	 *
> 	 * Output:
> 	 *       the number of gnomothings gnomoacted on.
> 	 *
> 	 * Description:	
> 	 *  blah blah blah. 
> 	 */
> 
> Also include some kind of parseable header at the beginning of the
> file that describes the author, general description and so on.

Can we please use javadoc like documentation!? The comments for the
documentation starts with /** 

Here's an example:

/**
 * here is the description for the following class, method, variable, ...

 * @author Christian Leutloff 
 * @version 0.1, 06.02.1998
 */

public class ...
{
   /**
    * the first function
    * @param initialValue
    * @return something useful
    */
   public usefulType firstFunc(initType inital)
   {
...


The javadoc program generates from these comments really useful
documentation. Look at the JDK documentation which is generated with
javadoc.

Bye
  Christian

-- 
Christian Leutloff, Aachen, Germany         leutloff@sundancer.oche.de  
      http://www.oche.de/~leutloff/         leutloff@debian.org      

            Debian GNU/Linux - http://www.de.debian.org/

PGP signature