[Libevent-users] Re: [PATCH] libevent doxygen API documentation

[Mark Heily]

On Thu, 2007-08-09 at 09:40 -0400, Niels Provos wrote:
> Hi Mark,
> 
> I am at USENIX Security right now and even less responsive than usual.
>   I like code documentation.  I don't have much experience with
> doxygen.   However, if you could provide me with a patch against the
> existing header files, I am sure that we could start maintaining
> doxygen documentation inline with the main code.
> 

Niels,

Here is the patch that adds Doxygen documentation comments to the
public libevent header files. After applying the patch, you can execute
the 'doxygen' command to generate the API reference manual in HTML
format. The generated files are created under the 'doxygen/html'
subdirectory. 

This patch applies cleanly to revision 428 of the trunk as of 9/11/2007.

Enjoy,

  Mark

----

Copyright disclaimer:

I, Mark Heily, hereby place the following modifications to libevent into
the public domain. Hence, these modifications may be freely used and/or
redistributed for any purpose with or without attribution and/or other notice.

> On 8/3/07, Mark Heily <mark at heily.com> wrote:
> > If you like the idea of self-documenting code, I could redo the patch to
> > annotate the real event.h and evdns.h, instead of creating a copy in the
> > doxygen/ subdirectory. This makes it easier to keep the code and
> > documentation in sync in the future; when you change the code, change
> > the documentation with it. If the two things are kept separate, they can
> > fall out of sync more easily.
> >
> >
> > Best regards,
> >
> > Mark
> >
> > On Mon, 2007-07-30 at 20:32 -0700, Niels Provos wrote:
> > > Hi Mark,
> > >
> > > I am slowly catching up on my email back log.   Could you please check
> > > if your doxygen patch still works against  trunk?
> > >
> > > Thank you,
> > >  Niels.
> > >
> > > On 4/30/07, Mark Heily <mark at heily.com> wrote:
> > > > Here are the annotated header files and the Doxygen configuration file
> > > > that can be used to generate the libevent API reference manual found at
> > > > http://naturalc.org/libevent/.
> > > >
> > > > This patch creates the following files:
> > > >
> > > >    doxygen/
> > > >    doxygen/Doxyfile
> > > >    doxygen/event.h
> > > >    doxygen/evdns.h
> > > >    doxygen/evhttp.h
> > > >
> > > > It also modifies Makefile.am to include these files in the source
> > > > tarball when running 'make dist'.
> > > >
> > > > After applying the patch, go to the doxygen/ subdirectory and run
> > > > 'doxygen' to generate the documentation.
> > > >
> > > > Regards,
> > > >
> > > >   - Mark
> > > >
> > > > P.S. For legal purposes,
> > > >
> > > > I, Mark Heily, hereby place the following modifications to libevent into
> > > > the public domain. Hence, these modifications may be freely used and/or
> > > > redistributed for any purpose with or without attribution and/or other
> > > > notice.
> > > >
> > > > diff -ruN ../libevent.OLD/doxygen/Doxyfile ./doxygen/Doxyfile
> > > > --- ../libevent.OLD/doxygen/Doxyfile    1969-12-31 19:00:00.000000000 -0500
> > > > +++ ./doxygen/Doxyfile  2007-04-30 23:02:31.000000000 -0400
> > > > @@ -0,0 +1,226 @@
> > > > +# Doxyfile 1.5.1
> > > > +
> > > > +# This file describes the settings to be used by the documentation system
> > > > +# doxygen (www.doxygen.org) for a project
> > > > +#
> >
> >
-------------- next part --------------
A non-text attachment was scrubbed...
Name: libevent-inline-doxygen.patch
Type: text/x-patch
Size: 58133 bytes
Desc: not available
Url : http://monkeymail.org/archives/libevent-users/attachments/20070911/18c5f3bd/libevent-inline-doxygen-0001.bin