www.digitalmars.com         C & C++   DMDScript  

digitalmars.D - unittest ddoc.

reply Gor Gyolchanyan <gor.f.gyolchanyan gmail.com> writes:
I noticed, that a great way to document code is to put the contents of
its unittest in an example block of the respective ddoc:

/**
  * Transmogrifies an integer.
  * Params:
  *     integer = The integer, that will be transmogrified.
  * Returns:
  *     The transmogrified version of the integer.
  * Examples:
  * -----
  * assert(transmogrify(1) == 3);
  * assert(transmogrify(4) == 9);
  * assert(transmogrify(7) == 15);
  * -----
  */
int transmogrify(int integer)
{
    return integer * 2 + 1;
}
unittest
{
    assert(transmogrify(1) == 3);
    assert(transmogrify(4) == 9);
    assert(transmogrify(7) == 15);
}

The unittest is useful for both ensuring the expected behavior of the
code and to demonstrate it in a use case.
Wouldn't it be great if the compiler inserted the body of the unittest
ino the ddoc as an example? The condition to make that happen could be
the existence of ddoc comments on the code (at least empty) and the
unittest, in which case the text of the ddoc comment of the unittest
(if any) would be inserted right before the example.
This would automatically make any ddoc-commented and unittested code
documented with examples, which dramatically improve the learning
curve of the code being written.

-- 
Bye,
Gor Gyolchanyan.
Jan 30 2012
next sibling parent reply David Nadlinger <see klickverbot.at> writes:
On 1/30/12 5:39 PM, Gor Gyolchanyan wrote:

 Wouldn't it be great if the compiler inserted the body of the unittest
 ino the ddoc as an example?



At least for me, unit tests tend to be more complex/convoluted than 
example code, because they cover different edge cases, etc., so I'd 
rather go the opposite direction: allow automatic extraction of 
»Example:« blocks as unit tests (this has also been proposed for Phobos 
before).

David
Jan 30 2012
parent reply Don Clugston <dac nospam.com> writes:
On 30/01/12 18:35, Marco Leise wrote:

 Am 30.01.2012, 17:45 Uhr, schrieb David Nadlinger <see klickverbot.at>:


 On 1/30/12 5:39 PM, Gor Gyolchanyan wrote:

 Wouldn't it be great if the compiler inserted the body of the unittest
 ino the ddoc as an example?






 Yeah the idea is reaching far back.


 At least for me, unit tests tend to be more complex/convoluted than
 example code, because they cover different edge cases, etc., so I'd
 rather go the opposite direction: allow automatic extraction of
 »Example:« blocks as unit tests (this has also been proposed for
 Phobos before).

 David



 This obfuscates the language too much. A comment shouldn't be executed,
 come on :p
 What about:

 unittest(ddoc) {
 ... Readable use case example goes here ...
 }

 - or -

 example {
 ...
 }



OR:
/** optionally explain what this test is doing */
unittest {.... }
Jan 30 2012
parent reply Don Clugston <dac nospam.com> writes:
On 30/01/12 19:28, Marco Leise wrote:

 Am 30.01.2012, 18:55 Uhr, schrieb Don Clugston <dac nospam.com>:


 OR:
 /** optionally explain what this test is doing */
 unittest {.... }



 Not bad. So a documented unittest would be turned into an example
 section with "optinally explain what this test is doing" in DDoc?



Yes.
Has the advantage that it doesn't require any new syntax.
Jan 30 2012
parent Kapps <Kapps NotValidEmail.com> writes:
On 30/01/2012 12:34 PM, Don Clugston wrote:

 On 30/01/12 19:28, Marco Leise wrote:

 Am 30.01.2012, 18:55 Uhr, schrieb Don Clugston <dac nospam.com>:


 OR:
 /** optionally explain what this test is doing */
 unittest {.... }



 Not bad. So a documented unittest would be turned into an example
 section with "optinally explain what this test is doing" in DDoc?



 Yes.
 Has the advantage that it doesn't require any new syntax.



I really like this suggestion. Encourages unit tests AND encourages 
examples while providing a nice way to do both, removing a bunch of 
boilerplate code, and not breaking any existing code.
Jan 31 2012
prev sibling next sibling parent "Marco Leise" <Marco.Leise gmx.de> writes:
Am 30.01.2012, 17:45 Uhr, schrieb David Nadlinger <see klickverbot.at>:


 On 1/30/12 5:39 PM, Gor Gyolchanyan wrote:

 Wouldn't it be great if the compiler inserted the body of the unittes=







 ino the ddoc as an example?






Yeah the idea is reaching far back.


 At least for me, unit tests tend to be more complex/convoluted than  =




 example code, because they cover different edge cases, etc., so I'd  =




 rather go the opposite direction: allow automatic extraction of  =




 =C2=BBExample:=C2=AB blocks as unit tests (this has also been proposed=





 before).

 David



This obfuscates the language too much. A comment shouldn't be executed, =
 =

come on :p
What about:

	unittest(ddoc) {
		... Readable use case example goes here ...
	}

	- or -

	example {
		...
	}
Jan 30 2012
prev sibling next sibling parent "Marco Leise" <Marco.Leise gmx.de> writes:
Am 30.01.2012, 18:55 Uhr, schrieb Don Clugston <dac nospam.com>:


 OR:
 /** optionally explain what this test is doing */
 unittest {.... }



Not bad. So a documented unittest would be turned into an example section  
with "optinally explain what this test is doing" in DDoc?
Jan 30 2012
prev sibling next sibling parent "Felix Hufnagel" <suicide xited.de> writes:
+1
Jan 30 2012
prev sibling next sibling parent Gor Gyolchanyan <gor.f.gyolchanyan gmail.com> writes:
That's what I said in the original message. I proposed to do this only
if the unittest has a ddoc comment. :-)

On Mon, Jan 30, 2012 at 10:34 PM, Don Clugston <dac nospam.com> wrote:

 On 30/01/12 19:28, Marco Leise wrote:

 Am 30.01.2012, 18:55 Uhr, schrieb Don Clugston <dac nospam.com>:


 OR:
 /** optionally explain what this test is doing */
 unittest {.... }




 Not bad. So a documented unittest would be turned into an example
 section with "optinally explain what this test is doing" in DDoc?




 Yes.
 Has the advantage that it doesn't require any new syntax.





-- 
Bye,
Gor Gyolchanyan.
Jan 30 2012
prev sibling parent Jens Mueller <jens.k.mueller gmx.de> writes:
Kapps wrote:

 On 30/01/2012 12:34 PM, Don Clugston wrote:

On 30/01/12 19:28, Marco Leise wrote:

Am 30.01.2012, 18:55 Uhr, schrieb Don Clugston <dac nospam.com>:


OR:
/** optionally explain what this test is doing */
unittest {.... }



Not bad. So a documented unittest would be turned into an example
section with "optinally explain what this test is doing" in DDoc?



Yes.
Has the advantage that it doesn't require any new syntax.



 I really like this suggestion. Encourages unit tests AND encourages
 examples while providing a nice way to do both, removing a bunch of
 boilerplate code, and not breaking any existing code.



You can vote for it to hopefully raise some attention.
http://d.puremagic.com/issues/show_bug.cgi?id=2630

Jens
Jan 31 2012