Mirror of the Rel4tion website/wiki source, view at <http://rel4tion.org>

Clone

HTTPS: git clone https://vervis.peers.community/repos/yEzqv

SSH: git clone USERNAME@vervis.peers.community:yEzqv

Branches

• master

Tags

api-reference.mdwn

Issues to take care of:

• comment type
• usage with paramaters and members
• making sure it works with template parameters
• what should be documented and where
  • whether to document namespaces and where
  • whether to document files and where
  • whether to document private members
  • where, whether and how to write detailed descriptions for classes
• how tutorials get integrated with doxygen docs
• config file to use (compare with mm-common’s config file)
• whether to use doxywizard
• add doxygen usage to autotools setup
• usage of markdown
• rules for special commands (e.g. @author)
• whether man and info should be used, and whether they can/should be created by/using doxygen

Interesting commands:

• structure indicators
  • internal, endinternal to mark internal docs generated only if INTERNAL_DOCS is YES
  • example, to mark docs for code example and make it appear under Examples tab in HTML output
  • file, to document a file. For certain files it’s required (e.g. files with just typedefs and/or free functions)
  • grouping: ingroup, defgroup, addgroup, weakgroup
  • mainpage, to create main page file
  • name, for member grouping in classes with many members
  • namespace, useful for documenting a namespace in one place
  • overload, to easily mark convenience overloads of functions
  • page, to create a page of documentation
  • relates & relatesalso for marking free functions related to classes but aren’t friends (e.g. operator <<, std::hash speci, etc.)
• section indicators
  • simply everything here! All of it is very useful!
• commands to create links
  • anchor, to mark lines in pages and mainpage, and refer to them from other places
  • link and ref, to make references to objects/functions/members
  • subpage, do define a tree hierarchy of pages
  • tableofcontents to insert TOC of sections and subsections of a long page
  • section, subsection, subsubsection, paragraph
• commands for displaying examples
  • all are useful for embedding source code examples in the docs
• command for visual enhancements
  • all are useful for doc text

Tasks:

• Prepare doxygen config file
• Prepare stylesheet
• prepare generation script/make target
• create checklist for writing class/component docs, i.e. what it should contain: typical usage, notes, advanced usage, tips…
• create checklist for inline docs: params, newin, return, throws, deprecation status, see also, etc.