httpd-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Life is hard, and then you die" <ron...@innovation.ch>
Subject Re: pod2text
Date Thu, 01 Jun 2000 18:19:14 GMT

On Thu, Jun 01, 2000 at 10:53:57AM -0700, Greg Stein wrote:
> 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).

I agree. Putting the docs in the source means you have to duplicate them
and keep them up to date in multiple places (and which platform then
becomes the "master" for generating them?). Also, as a user of apr, when
I'm looking for a function I go to the headers, not the source, and
hence that's where the docs should be (otherwise I have to do yet
another step of finding where that function is implemented and reading
the docs there). OTOH, having good generated docs around makes this less
of a problem (i.e. I needn't look at the header files or source at all).

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

Again I agree. I see Ryan's point, but with comments clearly demarcated
as in the example below I find I can quite easily scan through the
headers.


  Cheers,

  Ronald


> 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