Documentation
●
●
●
Documentation is just as important as the code
itself.
Without docs, you wouldn't know how to use a
library. cppreference.com or the ROOT docs are
essential.
You should make sure you always document
your code for external use.
1
Documentation
●
●
●
●
All classes, functions and data members should
be commented
A class comment should describe what the class
is used for and how to use it
A function comment should describe all
arguments, the return value, any side effects
and if applicable any pre- or post- conditions
A standard syntax exists called Doxygen
2
Doxygen
●
●
●
Doxygen uses a special comment block syntax.
Single line comments start with /// and multiline comments start with /**
It defines a number of special commands which
start with a backslash for structured information
Documentation comment comes just before the
thing it is annotating
3
Adding it to CMake
●
●
Doxygen is a program which, given a
configuration file, generates a set of HTML files
A default config file can be created with
$ doxygen -G Doxyfile
but we will just use the one provided in the
mpags-cipher git repo in the Documentation
folder.
●
It's a simple (if long) file so feel free to read
through it
4
Documentation/CMakeLists.txt
#Find the Doxygen tools
find_package(Doxygen REQUIRED)
#Copy Doxyfile.in to Doxyfile and replace any @VAR@ with with CMake variables
called VAR
configure_file(
${CMAKE_CURRENT_LIST_DIR}/Doxyfile.in
${CMAKE_CURRENT_BINARY_DIR}/Doxyfile
@ONLY
)
#Tells CMake how to 'create' ${CMAKE_CURRENT_BINARY_DIR}/html/index.html
add_custom_command(
OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/html/index.html
COMMAND ${DOXYGEN_EXECUTABLE} ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile
WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile mpags-cipher
)
#Adds the ability to do 'make doc' which will try to create ".../html/index.html"
add_custom_target(doc ALL DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/html/index.html)
5
Exercise 1
●
●
●
●
Download Documentation/Doxyfile.in and
Documentation/CMakeLists.txt to your own
project from mpags-cipher.
Edit your main CMakeLists.txt to add the
Documentation subdirectory.
Run make doc
Open mpags-cipher.build/Documentation/
html/index.html
6
Doxygen syntax
●
Doxygen comments are marked in a special way
/**
* Doxygen comments start with a slash and two stars
* Doxygen reads what's inside the comment
*/
●
●
Comments precede the statement that they
want to document.
Doxygen provides its own syntax to be used
inside comments. They are detailed in full in
the manual but there are a few which are most
commonly used.
7
Doxygen commands
●
The first line briefly describes the construct
/**
* This function is amazing and does something very special
*/
void foo();
●
\param is used for arguments to functions
/**
* \param n the element to foo
*/
void foo(const int n);
●
\return is used to describe the return value
/**
* \return the number of elements
*/
int size();
8
Function example
●
●
Always document all function parameters and
return values.
Describe a function in detail if possible
/**
* An amazing function which does something very special
*
* A longer description of this function is that is can be used
* to do something very interesting which this longer description
* explains in detail.
*
* \param thing the string that we want to convert
*
* \return the converted string
*/
std::string convert(const std::string& thing);
9
Class example
●
Class docs should describe the purpose of the
class and give examples of usage
/**
* A cipher encodes and decodes
*
* Cipher is an abstract base class which provides the ability to
* encode and decode strings based on a key
*
* Use it like
* \code{.cpp}
class MyCipher : public Cipher {...};
* \endcode
*
* \since 0.1.3
*/
class Cipher {
10
Enum example
●
Enums should have each member documented
●
Use 'suffix' comments
/**
* The rank of the employee
*/
enum class Rank {
Junior, ///< A new person at the company
Senior, ///< Someone who has been here a while
Chief ///< Someone super special
};
11
Separate page example
●
Create a file called MPAGSCipher/mpagscipher.dox
/**
* \mainpage Welcome to MPAGS Cipher
*
* Blah blah
*
* \section Introduction
* Blah blah
*
* \subsection Usage
*
* \code{.cpp}
CaesarCipher c {"4"};
std::cout << c.encode("test");
* \endcode
*/
12
Exercise 2
●
●
●
●
Add documentation for a number of different
things in your code.
Try out the different Doxygen commands
Check the Doxygen output for any warnings or
errors.
Look though Doxyfile.in for any interesting
settings to change.
13