Mailing-List: contact new-httpd-help@apache.org; run by ezmlm
Precedence: bulk
Reply-To: new-httpd@apache.org
Message-Id: <4.3.1.2.20000601100610.00b1b2d0@pop.ma.ultranet.com>
Date: Thu, 01 Jun 2000 10:09:28 -0400
To: new-httpd@apache.org
From: Greg Marr <gregm@alum.wpi.edu>
Subject: Re: pod2text
In-Reply-To: <20000601014828.B10078@innovation.ch>
References: <200005222227.aa13273@gremlin-relay.ics.uci.edu>
 <Pine.LNX.4.21.0005191443140.1915-100000@koj.rkbloom.net>
 <200005222227.aa13273@gremlin-relay.ics.uci.edu>
Mime-Version: 1.0
Content-Type: text/plain; charset="us-ascii"; format=flowed

At 04:48 AM 06/01/2000, Life is hard, and then you die wrote:
>I'm I the only one who is really detesting the pod docs? I find
>they make the files very unreadable:
>
>I really love javadoc, and hence would like to see DOC++ used instead:
>
>     /**
>      * Create a pool of shared memory for use later.
>      *
>      * @param m       The shared memory block.
>      * @param reqsize The size of the shared memory pool.
>      * @param file    The file to use for the shared memory on 
> platforms that
>      *                require it.
>      * @param cont    The pool to use
>      * @return APR_SUCCESS if successful; an error code otherwise
>      */

I use Autoduck at work, (I found it and brought it in, and now we're 
using it everywhere) and it's very similar to this style.  (Autoduck 
is a free program written by someone who was at the time a MS 
programmer, but who has since left the company.  It's probably not 
very portable though.)

>To me this is far more readable. This also has the potential of 
>being able to check that all the arguments are documented (not 
>currently done in DOC++, though), and it creates links to the 
>definitions of the types used in the arguments.

I agree.

--
Greg Marr
gregm@alum.wpi.edu
"We thought you were dead."
"I was, but I'm better now." - Sheridan, "The Summoning"