httpd-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From r..@covalent.net
Subject Re: pod2text
Date Thu, 01 Jun 2000 14:31:48 GMT

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
-------------------------------------------------------------------------------


Mime
View raw message