Code documentation & C++

Documentation prepared inside the code can be useful for API or module documentation when you need to publish descriptions of your classes and functions in form other than comments-in-code. Usually such a documentation is created in form of special comments and then exported automatically using specialized tools in form of nice HTML-s.


Doxygen is currently my tool of choice for code documentation. It exports documentation in form of static HTML files with search function included. It's free and does not force you to write too much in addition to standard comments.

Example function prepared to be processed by doxygen:

/// Perform sort using "sort tool" - object with internal reference to container
/// @param[in] aSize Number of items to be sorted
/// @param[in] sortTool object with interface: { value_type, int compare(pos, value); T get(pos); swap(pos1, pos2) }
template<class SortTool>
void sort(size_t aSize, SortTool sortTool)
  Details::dtpQuickSorter<SortTool> sorter(aSize, sortTool);
  if (aSize > 1)
    sorter.execute(0, aSize - 1);