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

[Leon Woestenberg]

Hello Kieran, Adam and others,

> > > What do you guys thinks of self-documenting source code?
> > >
> > > 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
>
First of all, I was thinking of formal documentation of the API functions
first,
covering all possible input conditions/values and output conditions/values.
Internal data structures and internal source documentation on implementation
may follow up later.

> 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.
>
Yes, but on a low level of priority. In my daily work, I'm just
"maintaining"
compatibility with the lwIP stack as a side-project now, documentation being
one issue of that. And glad to hear the second opinion on Doxygen.

As said, I'll start with the DHCP client and cs8900 driver, as I am supposed
to understand to the bit what happens there :)

Leon.

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