[lwip-users] Re: [lwip] lwIP source code documentation proposal

[Kieran Mansley]

On Wed, 8 May 2002, Adam Dunkels wrote:

> Hi!
>
> On Wednesday 08 May 2002 11.36, address@hidden wrote:
> > Adam, welcome back :)
>
> Thanks! :-)
>
> > There have been some discussions on documentation on lwIP.
> >
> > What do you guys thinks of self-documenting source code?
> >
> > I have recently been using the JavaDoc standard to document my own C
> > sources, that can be easily extracted and neatly formatted HTML, PDF,
> > whatever is generated by open-source tools such as doxygen(.org).
> >
> > I feel that especially the function calls to lwIP need more documentation
> > in
> > order for newbies to understand how to use the stack.
> >
> > Choosing self-documenting source code (and a format,; JavaDoc) would
> > help us submit not only code, but also documentation.
>
> Definately a good idea! Can doxygen work directly with JavaDoc comments?

Yes, I believe so.  It can certainly use the same grammar.  I agree that
it's a good idea, but a pain to implement in retrospect.  Doing it as code
is created is much easier.  Perhaps people should volunteer to do one
portion of code that they think they understand well, so that the load
isn't all on one person?  We would need some guidelines about the style
and content to include though - would you be willing to create a sample
that others could work to Leon?  Doxygen would (for me) be the preferred
tool to use.

Thanks

Kieran

[This message was sent through the lwip discussion list.]