2009/3/2 Stefano Sabatini <ssabat...@reilabs.com>: > Is it OK what in subject? > > I think the rationale is quite obvious, docs should be documented in > the interface rather than in the implementation, also this avoids > duplication.
I think the documentation should as close to implementation as possible. For C, it means that the macros, public structs, etc. should be documented in .h files, functions in .c files. This way there is much better chances that the documentation gets updated when the functionality is updated. The interface gets documented in one place, however, thanks to Dimitri van Heesch and Doxygen. I think most editors can get from headers to doxygen-generated docs in a couple of keystrokes or mouse clicks. Or to the source code, if you prefer raw @annotation. For Sofia, it is a bit ambiguous how to document tags as there is not much to implement. The type-casting function is declared within the macro in *.h and the actual name and type in *.c. I prefer a short list *.h files and in some Sofia SIP modules I have moved the documentation into the *_tag.c files. Other problematic things include the platform-specific parts of su modules. Generally separating documentation from implementation creates extra work that is needed to get the documentation updated. That extra work has a tendency of not getting done as you might have noticed from those @briefs now in *.h files. > If that's OK I'll post here some patches for doing that, one header at > a time. If you want to get rid of duplicate and contradictory @brief entries I'd prefer removing the extra @brief comments from headers rather than collecting the documentation to the *.h files. -- Pekka.Pessi mail at nokia.com ------------------------------------------------------------------------------ Open Source Business Conference (OSBC), March 24-25, 2009, San Francisco, CA -OSBC tackles the biggest issue in open source: Open Sourcing the Enterprise -Strategies to boost innovation and cut costs with open source participation -Receive a $600 discount off the registration fee with the source code: SFAD http://p.sf.net/sfu/XcvMzF8H _______________________________________________ Sofia-sip-devel mailing list Sofia-sip-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/sofia-sip-devel
