Re: [lwip-users] doxygen documentation

[chrysn]

hi,

On Thu, Jan 17, 2013 at 03:56:45PM +0100, chrysn wrote:
> * an updated online documentation would be great, possibly in a new
>   subdirctory reflecting the version, so we can have documentation for
>   1.3.0 (seems to be widespread still?), 1.4.1 and development at the
>   same time.

i've created a new Doxyfile that is supposed to give usable results with
1.4.1.

unfortunately, it seems that the state of doxygenized docstrings has
been rotting along, probably due to the doxygen docs often not being
built by developers. examples thereof are missing @file specifiers for
per-file comments (which get added to the comments of the next
documentable entity), missing doxygen marks around @todo items or
non-doxygen comments for batch #define lines (eg the ERR_* section).

functions being documented at the implementation and the header is a
decision i understand (and sometimes even like), but it requres doxygen
to go through the *.c files too. that's not a problem per se (doxygen
merges the descriptions from the *.c and *.h files, if there are any),
but the functions end up being described in both places, and users might
easily find their interface documentation on the same page as the
internal constants and data structures of that module, and not find the
#define lines from the respective header files there.

to combat that, i'd put @defgroup commands in all of the header files.
thus, the user accessible functions are described neatly in a tree-like
structure in the "modules" section of the resulting doxygen files. the
implementation details are still accessible via doxygen, and the
functions stay linked from there.


the results of having doxigenified README, doc/* and the UDP, DNS and
error subsystems (at least superficially) can be viewed for the time
being at [1]. the patch attached can be applied to the 1.4.1 version,
and generated that with doxygen 1.8.1.2. currently, quite many graphs
are enabled, i'd hav to see which are actually useful. those for structs
are, in my opinion; the call graphs will be more useful when a user
lwipopts.h can be applied, because then they'll show what's actually
happening stack-wise.


best regards
chrysn

[1] http://downloads.amsuess.com/lwip-1.4.1/html/

-- 
To use raw power is to make yourself infinitely vulnerable to greater powers.
  -- Bene Gesserit axiom

doxygen-preview.patch
Description: Text Data

signature.asc
Description: Digital signature