What do you use (tools or techniques) for documenting code for design decisions, code examples, history of API/ABI changes, graphical supplements (like design diagrams), etc?
I'd like to generate both webpages that have full details plus manpages that have the synopsis, descriptions, return values, etc, but not all the design decisions nor images (of course) nor code examples which may be too long for a succinct manual page. I don't want to document in multiple places -- don't want to be redundant. I'd like to keep this documentation very near the code (even embedded) so when code is updated, it is easy to remember or do the documentation also. The code is mostly a mix of Python and C++. Do you use pydoc and/or doxygen? I see doxygen can insert images into the documentation, so could be used to insert design diagrams. And doxygen has conditional \if and \ifnot for conditionally showing or not showing documentation (which could be used for manpages versus complete HTML). I don't see image or manual page support for pydoc. If you have any examples (original documentation and rendered results in HTML and man), please let me know. Also if you have any developer guidelines that include documentation guidelines, please let me know. _______________________________________________ freebsd-chat@freebsd.org mailing list http://lists.freebsd.org/mailman/listinfo/freebsd-chat To unsubscribe, send any mail to "freebsd-chat-unsubscr...@freebsd.org"
