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

[leon . woestenberg]

Hello all,

Adam, welcome back :)

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.

Example from a FireWire project:

/**
 * Write a register from the link layer.
 *
 * @param offset register offset (byte-address)
 * @param value value to be written
 *
 * @note This function may be pre-empted by itself, as long as the
pre-empting
 * call completes before the pre-empted call is resumed again.
 *
 * @see fw_link_read_reg fw_link_write_reg_byte
 */
void fw_link_write_reg(u8_t offset, quadlet_t value)
{
...
}

Regards,

Leon Woestenberg

Axon Digital Design
Phone: +31 13 511 6666
Fax: +31 13 511 4151
web: www.axon.tv

=====================================================================================================

The information contained in this communication is confidential and is
intended solely for the use of the individual or entity to whom it is
addressed. Axon Digital Design Group is neither liable for the proper nor
for the complete transmission of the information contained in this
communication nor for any delay in its receipt. Axon Digital Design Group
does not guarantee that the integrity of this communication has been
maintained nor that the communication is free of viruses, interceptions or
interference. If you are not the intended recipient of this communication,
you are hereby notified that reading, disseminating, distributing or
copying this message is strictly prohibited. In that case please return the
communication to the sender and delete and destroy all copies. In carrying
out its engagements, Axon Digital Design Group applies general terms and
conditions, which contain a clause that limits its liability. A copy of
these terms and conditions is available on request free of charge.
=====================================================================================================

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