www.digitalmars.com         C & C++   DMDScript  

digitalmars.D - [WORK] Simple and very useful stuff more of us could get into

reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
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
Jan 29 2015
parent reply FG <home fgda.pl> writes:
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
     {
         ...
     }
Jan 29 2015
parent reply "H. S. Teoh via Digitalmars-d" <digitalmars-d puremagic.com> writes:
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.
Jan 29 2015
parent reply FG <home fgda.pl> writes:
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
Jan 29 2015
parent Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
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
Jan 29 2015