[WORK] Simple and very useful stuff more of us could get into

[H. S. Teoh via Digitalmars-d]

On Thu, Jan 29, 2015 at 11:44:46PM +0100, FG via Digitalmars-d wrote:
> I don't understand. Does putting an empty ddoc comment before a
> unittest make the code inside the unittest appear in the documentation
> as if it was an Examples: section? Is this behaviour documented
> anywhere?
> 
>     ///
>     unittest
>     {
>         ...
>     }

This is the so-called "documented unittest" or "ddoc'd unittest". It's
an awesome feature implemented (IIRC) by Andrey Mitrovic that ensures
that generated doc examples are compilable and runnable. Preferably all
code examples in Phobos should be ddoc'd unittests, so that they won't
suffer from bitrot.

If this feature isn't documented yet, it should be! Please submit a PR.
(OK OK, file a bug at least!) :-P

Note that the comment doesn't have to be empty; it's perfectly possible
to put explanations in there, for example:

	/**
	 * My awesome function.
	 */
	auto myAwesomeFunc(...) { ... }

	/// This example shows just how awesome this function is:
	unittest
	{
		assert(myAwesomeFunc(0) == 0);
	}

The generated docs will look something like this:

	auto myAwesomeFunc(...);

		My awesome function.

		This example shows just how awesome this function is:

			assert(myAwesomeFunc(0) == 0);


T

-- 
The best way to destroy a cause is to defend it poorly.