Writing Documentation

Documentation is written either in Doxygen style, inline with the source code, for the API documentation or in reStructured Text for this handbook.

Extracting Examples

Whenever you write documentation for a piece of code it should remain valid throughout the lifetime of that code. If the code changes, the documentation should be adopted. However, this is a tedious process and cannot be automated. Human beings often forget to update the documentation whenever their code changes.

Therefore, it is explicitely encouraged to extract examples from unit tests that are contained within the main test suite. The commit policy enforces that all tests in the main test suite must succeed before commiting. If you extract your examples from these tests, then it is quite clear that all your examples will either remain valid or will be changed by developers if the break them.

You can mark a code snippet by using the begin example and endexample environment. The examples will be automatically extracted by playground.py and will be made available to Doxygen and Sphinx for reference. Below is an example of this.

// begin example "wns.avaragetest.header.example"
#include <WNS/Average.hpp>
#include <WNS/TestFixture.hpp>

namespace wns { namespace tests {
          class AverageTest : public CppUnit::TestFixture  {
                CPPUNIT_TEST_SUITE( AverageTest );
                CPPUNIT_TEST( testPutAndGet );
                CPPUNIT_TEST( testReset );
                CPPUNIT_TEST_SUITE_END();
             public:
                void setUp();
                void tearDown();
                void testPutAndGet();
                void testReset();
             private:
                Average<double> average;
          };
 }}
 // end example

Including Examples in the API Documentaion

You can include an example in some other doxygen documentation by using the @include statement of Doxygen. Just reference your example by its name and it will be rendered in place.

/**
 * @page wns_AboutTheAverageTest About the Average Test
 *
 * The @c AverageTest is used to test @c wns::Average. Its class
 * definition is as follows:
 *
 * @include wns.avaragetest.header.example
 */

Including Examples in Sphinx Manuals

You can include an example in reStructured Text as it is used by Sphinx with the literalinclude directive. This directive is used in this section to include the example above. The reST for this section is showed below the included example. Here is the example:

#include <WNS/Average.hpp>
#include <WNS/TestFixture.hpp>

namespace wns { namespace tests {
	class AverageTest : public CppUnit::TestFixture  {
		TEST_SUITE( AverageTest );
		TEST( testPutAndGet );
		TEST( testReset );
		TEST_SUITE_END();
	public:
		void setUp();
		void tearDown();
		void testPutAndGet();
		void testReset();
	private:
		Average<double> average;
	};
}}

The reST source for this section is:

Including Examples in Sphinx Manuals
------------------------------------

You can include an example in reStructured Text as it is used by
Sphinx with the ``literalinclude`` directive. This directive is
used in this section to include the example above. The reST for
this section is showed below the included example. Here is the
example:

.. literalinclude:: ../../../.createManualsWorkingDir/wns.avaragetest.header.example

The reST source for this section is: