On date Monday 2009-03-02 17:15:27 +0200, Pekka Pessi phoned this: > 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.
Indeed I don't consider this duplication a good idea, hopefully they should be documented in just a single point, either in the implementation or in the declaration. Since the headers are exposed to the user rather than the implementation (and not necessarily the user has the sources available), then I believe the documentation should go there. Doxygen is nice, but ask for the user to use JAT (Just Another Tool) means to add another layer of complexity on him, and I like the idea to simply read the headers and get all what I need (declaration *and* documentation). Also I still have to figure out a good way to integrate doxygen with emacs (but I'll do as I'll have more time). > > 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. OK. Regards. ------------------------------------------------------------------------------ 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
