Consider the following C++ header file named swap.hpp:
#include <type_traits>
namespace std
{
/// \effects Exchanges values stored in two locations.
/// \requires Type `T` shall be `MoveConstructible` and `MoveAssignable`.
template <class T>
void swap(T &a, T &b) noexcept(is_nothrow_move_constructible<T>::value &&
is_nothrow_move_assignable<T>::value);
}
This will generate the following documentation:
#Header file swap.hpp
#include <type_traits>
namespace std
{
template <typename T>
void swap(T & a, T & b) noexcept(is_nothrow_move_constructible<T>::value &&
is_nothrow_move_assignable<T>::value);
}
##Function template swap<T>
template <typename T>
void swap(T & a, T & b) noexcept(is_nothrow_move_constructible<T>::value &&
is_nothrow_move_assignable<T>::value);
Effects: Exchanges values stored in two locations.
Requires: Type T shall be MoveConstructible and MoveAssignable.
The example makes it already clear: Standardese aims to provide a documentation in a similar way to the C++ standard - hence the name.
This means that it provides commands to introduce so called sections in the documentation.
The current sections are all the C++ standard lists in [structure.specifications]/3 like \effects, \requires, \returns and \throws.
Read more in the introductory blog post.