httpd-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Greg Stein <gst...@lyra.org>
Subject Re: pod2text
Date Thu, 01 Jun 2000 17:53:57 GMT
I think that they should stay in the header. Since the APR file structure
allows for multiple implementations, then the header is the single point
for the docs (conversely: duplicating the docs across files will lead to
skew much more easily).

Using a different format should clean up the headers, so they are more
readable.

Cheers,
-g

On Thu, 1 Jun 2000 rbb@covalent.net wrote:
> I think the pod makes the files absolutely horrible.  However, when the
> docs were originally written, they were with the actual source, not with
> the prototypes.  This made the ratio of code to API doc much easier to
> manage.  It has been a complaint of mine that having ANY API docs in the
> header files makes the headers that much harder to read simply because the
> ratio is backwards.
> 
> Ryan
> 
> > I'm I the only one who is really detesting the pod docs? I find
> > they make the files very unreadable:
> > 
> >     /*
> > 
> >     =head1 ap_status_t ap_shm_init(ap_shmem_t *m, ap_size_t reqsize, char *file)
> > 
> >     B<Create a pool of shared memory for use later.>
> > 
> > 	arg 1) The shared memory block.
> > 	arg 2) The size of the shared memory pool.
> > 	arg 3) The file to use for the shared memory on platforms that
> > 	       require it.
> > 	arg 4) The pool to use
> > 
> >     =cut
> >      */
> >     ap_status_t ap_shm_init(ap_shmem_t **m, ap_size_t reqsize, const char *file,
ap_pool_t *cont);
> > 
> >     /*
> > 
> >     =head1 ap_status_t ap_shm_destroy(ap_shmem_t *m)
> > 
> >     B<Destroy the shared memory block.>
> > 
> > 	arg 1) The shared memory block to destroy.
> > 
> >     =cut
> >      */
> >     ap_status_t ap_shm_destroy(ap_shmem_t *m);
> > 
> > Without syntax coloring and with all those extra empty lines it now
> > becomes really painful to separate the comments from the code. Also,
> > having to duplicate the declaration doesn't help.
> > 
> > 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
> >      */
> >     ap_status_t ap_shm_init(ap_shmem_t **m, ap_size_t reqsize, const char *file,
ap_pool_t *cont);
> > 
> >     /**
> >      * Destroy the shared memory block.
> >      * 
> >      * @param m  The shared memory block to destroy.
> >      * @return APR_SUCCESS if successful; an error code otherwise
> >      */
> >     ap_status_t ap_shm_destroy(ap_shmem_t *m);
> > 
> > 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.
> > 
> > As far as Roy's comment about DOC++ less likely to be installed, I'm not
> > too worried about that, as you only need it installed if you want to
> > generate the docs - periodic doc generation (once or twice a day) on
> > locus would certainly reduce that need to a minimum.
> 
> 
> _______________________________________________________________________________
> Ryan Bloom                        	rbb@apache.org
> 406 29th St.
> San Francisco, CA 94131
> -------------------------------------------------------------------------------
> 

-- 
Greg Stein, http://www.lyra.org/


Mime
View raw message