• Gor Gyolchanyan (38/38) Jan 30 2012 I noticed, that a great way to document code is to put the contents of
• David Nadlinger (7/9) Jan 30 2012 At least for me, unit tests tend to be more complex/convoluted than
• Marco Leise (15/24) Jan 30 2012 Yeah the idea is reaching far back.
• Don Clugston (4/26) Jan 30 2012 OR:
• Marco Leise (3/6) Jan 30 2012 Not bad. So a documented unittest would be turned into an example sectio...
• Don Clugston (3/9) Jan 30 2012 Yes.
• Felix Hufnagel (1/1) Jan 30 2012 +1
• Gor Gyolchanyan (6/19) Jan 30 2012 That's what I said in the original message. I proposed to do this only
• Kapps (4/15) Jan 31 2012 I really like this suggestion. Encourages unit tests AND encourages
• Jens Mueller (4/21) Jan 31 2012 You can vote for it to hopefully raise some attention.

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.

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

"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=


t
 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=

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

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

"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?

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.

"Felix Hufnagel" <suicide xited.de> writes:

+1

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.

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.

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