https://github.com/D-Programming-Language/phobos/pull/2931. Doing such stuff is great for anyone considering improving the lot of dlang. Having more active and working documentation is definitely moving the needle in the right direction. -- Andrei

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
    {
        ...
    }

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.

On 2015-01-29 at 23:52, H. S. Teoh via Digitalmars-d wrote:
> 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.

Yes, it's great. Documentation and unittest combined, DRY, like Python's doctest.
It really should be mentioned on http://dlang.org/ddoc.html

On 1/29/15 3:17 PM, FG wrote:
> On 2015-01-29 at 23:52, H. S. Teoh via Digitalmars-d wrote:
>> 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.
>
> Yes, it's great. Documentation and unittest combined, DRY, like Python's
> doctest.
> It really should be mentioned on http://dlang.org/ddoc.html

Funny thing is this obvious-in-hindsight feature has had to go through a skepticism phase. Thanks Andrej Mitrovic for pushing it through! -- Andrei