www.digitalmars.com         C & C++   DMDScript  

digitalmars.D - documentable unittest

reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
I'm very happy that this will be part of the upcoming release: 
https://github.com/D-Programming-Language/dmd/pull/1342 (see also 
http://d.puremagic.com/issues/show_bug.cgi?id=2630) allows defining 
unittests that simultaneously work as documentation. This is a great way 
to simultaneously write meaningful tests and good documentation examples.

If you want to help, feel free to hop on the Phobos documentation and 
convert some of it to use the new feature.


Thanks,

Andrei
Feb 07 2013
next sibling parent reply "H. S. Teoh" <hsteoh quickfur.ath.cx> writes:
On Thu, Feb 07, 2013 at 05:53:59PM -0500, Andrei Alexandrescu wrote:
 I'm very happy that this will be part of the upcoming release:
 https://github.com/D-Programming-Language/dmd/pull/1342 (see also
 http://d.puremagic.com/issues/show_bug.cgi?id=2630) allows defining
 unittests that simultaneously work as documentation. This is a great
 way to simultaneously write meaningful tests and good documentation
 examples.
 
 If you want to help, feel free to hop on the Phobos documentation
 and convert some of it to use the new feature.

Woohoo!!! I'm going to update next[Even]Permutation and cartesianProduct to use this ASAP. Also, we should document this feature somewhere, preferably somewhere prominent, like the pages that describe the ddoc format, or the documentation for unittest blocks. I think it also deserves an article somewhere (on the wiki, on Dr. Dobbs, etc.). This is a very, very cool feature. T -- Almost all proofs have bugs, but almost all theorems are true. -- Paul Pedersen
Feb 07 2013
parent Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 2/7/13 6:06 PM, H. S. Teoh wrote:
 Also, we should document this feature somewhere, preferably somewhere
 prominent, like the pages that describe the ddoc format, or the
 documentation for unittest blocks.

 I think it also deserves an article somewhere (on the wiki, on Dr.
 Dobbs, etc.). This is a very, very cool feature.

Agreed on both. Andrej? Andrei
Feb 07 2013
prev sibling next sibling parent "H. S. Teoh" <hsteoh quickfur.ath.cx> writes:
On Thu, Feb 07, 2013 at 05:53:59PM -0500, Andrei Alexandrescu wrote:
 I'm very happy that this will be part of the upcoming release:
 https://github.com/D-Programming-Language/dmd/pull/1342 (see also
 http://d.puremagic.com/issues/show_bug.cgi?id=2630) allows defining
 unittests that simultaneously work as documentation. This is a great
 way to simultaneously write meaningful tests and good documentation
 examples.
 
 If you want to help, feel free to hop on the Phobos documentation
 and convert some of it to use the new feature.

Hmm. I notice that comments in the unittest are not included in the generated documentation. This is a bit unfortunate, if you wish to point out something in the example code. T -- Questions are the beginning of intelligence, but the fear of God is the beginning of wisdom.
Feb 07 2013
prev sibling next sibling parent "H. S. Teoh" <hsteoh quickfur.ath.cx> writes:
On Thu, Feb 07, 2013 at 03:16:04PM -0800, H. S. Teoh wrote:
 On Thu, Feb 07, 2013 at 05:53:59PM -0500, Andrei Alexandrescu wrote:
 I'm very happy that this will be part of the upcoming release:
 https://github.com/D-Programming-Language/dmd/pull/1342 (see also
 http://d.puremagic.com/issues/show_bug.cgi?id=2630) allows defining
 unittests that simultaneously work as documentation. This is a great
 way to simultaneously write meaningful tests and good documentation
 examples.
 
 If you want to help, feel free to hop on the Phobos documentation
 and convert some of it to use the new feature.

Hmm. I notice that comments in the unittest are not included in the generated documentation. This is a bit unfortunate, if you wish to point out something in the example code.

http://d.puremagic.com/issues/show_bug.cgi?id=9472 http://d.puremagic.com/issues/show_bug.cgi?id=9473 http://d.puremagic.com/issues/show_bug.cgi?id=9474 T -- Food and laptops don't mix.
Feb 07 2013
prev sibling next sibling parent "H. S. Teoh" <hsteoh quickfur.ath.cx> writes:
On Thu, Feb 07, 2013 at 03:34:24PM -0800, H. S. Teoh wrote:
 On Thu, Feb 07, 2013 at 03:16:04PM -0800, H. S. Teoh wrote:
 On Thu, Feb 07, 2013 at 05:53:59PM -0500, Andrei Alexandrescu wrote:
 I'm very happy that this will be part of the upcoming release:
 https://github.com/D-Programming-Language/dmd/pull/1342 (see also
 http://d.puremagic.com/issues/show_bug.cgi?id=2630) allows
 defining unittests that simultaneously work as documentation. This
 is a great way to simultaneously write meaningful tests and good
 documentation examples.
 
 If you want to help, feel free to hop on the Phobos documentation
 and convert some of it to use the new feature.

Hmm. I notice that comments in the unittest are not included in the generated documentation. This is a bit unfortunate, if you wish to point out something in the example code.

http://d.puremagic.com/issues/show_bug.cgi?id=9472 http://d.puremagic.com/issues/show_bug.cgi?id=9473 http://d.puremagic.com/issues/show_bug.cgi?id=9474

http://d.puremagic.com/issues/show_bug.cgi?id=9475 Sorry for being such a bugbear, ;-) but I really want to see this feature succeed! T -- Programming is not just an act of telling a computer what to do: it is also an act of telling other programmers what you wished the computer to do. Both are important, and the latter deserves care. -- Andrew Morton
Feb 07 2013
prev sibling next sibling parent Andrej Mitrovic <andrej.mitrovich gmail.com> writes:
On 2/8/13, H. S. Teoh <hsteoh quickfur.ath.cx> wrote:
 http://d.puremagic.com/issues/show_bug.cgi?id=9475

 Sorry for being such a bugbear, ;-) but I really want to see this
 feature succeed!

This is why we desperately need a way for users to test out new features before they're pushed to master. Nobody noticed any of these bugs even though the pull has been opened for a while now.
Feb 07 2013
prev sibling next sibling parent "H. S. Teoh" <hsteoh quickfur.ath.cx> writes:
On Fri, Feb 08, 2013 at 02:06:04AM +0100, Andrej Mitrovic wrote:
 On 2/8/13, H. S. Teoh <hsteoh quickfur.ath.cx> wrote:
 http://d.puremagic.com/issues/show_bug.cgi?id=9475

 Sorry for being such a bugbear, ;-) but I really want to see this
 feature succeed!

This is why we desperately need a way for users to test out new features before they're pushed to master. Nobody noticed any of these bugs even though the pull has been opened for a while now.

Maybe feature branches are what we need for this? Also, how many people actually check out code from pull requests to test them? I've confess I haven't been, I just look at the diffs and evaluate them. It's a lot of trouble to checkout an entire DMD + druntime + Phobos suite from a forked repos, along with setting things up so that the right version of DMD gets called when compiling your test, DMD finds the correct versions of stuff, etc., all just to try out a single pull request. Having new features immediately available (even in half-baked, incomplete, limping state) in a branch on the official repos will help a lot -- then one could just 'git checkout' the branch, rebuild, and run tests. If the feature proves to be unworkable, the branch can just be left unmerged (or deleted), and by the time it merges into master, it would hopefully have been sanity-tested enough that there are no big embarrassing problems left. It may even be possible to have an autobuilder build the branch, and put it up as one of the compilers you can select on the current dpaste site. Then people could even test the branch online just by typing code and selecting the branch! How cool would that be?? T -- Trying to define yourself is like trying to bite your own teeth. -- Alan Watts
Feb 07 2013
prev sibling next sibling parent "Steven Schveighoffer" <schveiguy yahoo.com> writes:
On Thu, 07 Feb 2013 20:20:44 -0500, H. S. Teoh <hsteoh quickfur.ath.cx>  
wrote:


 It may even be possible to have an autobuilder build the branch, and put
 it up as one of the compilers you can select on the current dpaste site.
 Then people could even test the branch online just by typing code and
 selecting the branch! How cool would that be??

Isn't the auto-tester already doing most of this? Why not just provide a place where auto-tester-created distribution can be downloaded? -Steve
Feb 07 2013
prev sibling next sibling parent Marco Leise <Marco.Leise gmx.de> writes:
Am Thu, 7 Feb 2013 16:10:52 -0800
schrieb "H. S. Teoh" <hsteoh quickfur.ath.cx>:

 http://d.puremagic.com/issues/show_bug.cgi?id=9475
 
 Sorry for being such a bugbear, ;-) but I really want to see this
 feature succeed!
 
 
 T

That's totally legit to report. I also want that feature to work well. Not because I'm personally using it much, but because it statically verifies correct Phobos examples. -- Marco
Feb 07 2013
prev sibling next sibling parent Marco Leise <Marco.Leise gmx.de> writes:
The next step could be to document function parameters inline.
That's where my experiment with Exception specifications led
me to. Instead of manually listing "Throws:" and "Params:" you
would add the comments right after the respective
exception/parameter. The benefit in terms of "reducing
dependencies":

1) DRY: You don't have to keep the Params: list in mind when
you add or rename a parameter. It will also be more obvious to
add a comment to a new parameter when the others have them.

2) You can document dummy parameters without giving them a
name first.

-- 
Marco
Feb 07 2013
prev sibling next sibling parent Chad Joan <chadjoan gmail.com> writes:
On 02/07/2013 05:53 PM, Andrei Alexandrescu wrote:
 I'm very happy that this will be part of the upcoming release:
 https://github.com/D-Programming-Language/dmd/pull/1342 (see also
 http://d.puremagic.com/issues/show_bug.cgi?id=2630) allows defining
 unittests that simultaneously work as documentation. This is a great way
 to simultaneously write meaningful tests and good documentation examples.

 If you want to help, feel free to hop on the Phobos documentation and
 convert some of it to use the new feature.


 Thanks,

 Andrei

YES YES YES. YES. YES> Thank you.
Feb 07 2013
prev sibling next sibling parent Marco Leise <Marco.Leise gmx.de> writes:
Am Thu, 07 Feb 2013 21:20:21 -0500
schrieb "Steven Schveighoffer" <schveiguy yahoo.com>:

 On Thu, 07 Feb 2013 20:20:44 -0500, H. S. Teoh <hsteoh quickfur.ath.cx>  
 wrote:
 
 
 It may even be possible to have an autobuilder build the branch, and put
 it up as one of the compilers you can select on the current dpaste site.
 Then people could even test the branch online just by typing code and
 selecting the branch! How cool would that be??

Isn't the auto-tester already doing most of this? Why not just provide a place where auto-tester-created distribution can be downloaded? -Steve

+1 It has to build DMD and Phobos anyway. Save energy, compile less! :D I would never build DMD myself to check out a pull request even IF I had an interest in the changes. I'm always thinking the QA department of DMD will check it all thoroughly. -- Marco
Feb 07 2013
prev sibling next sibling parent "H. S. Teoh" <hsteoh quickfur.ath.cx> writes:
On Fri, Feb 08, 2013 at 07:40:34AM +0100, Marco Leise wrote:
 Am Thu, 07 Feb 2013 21:20:21 -0500
 schrieb "Steven Schveighoffer" <schveiguy yahoo.com>:
 
 On Thu, 07 Feb 2013 20:20:44 -0500, H. S. Teoh <hsteoh quickfur.ath.cx>  
 wrote:
 
 
 It may even be possible to have an autobuilder build the branch, and put
 it up as one of the compilers you can select on the current dpaste site.
 Then people could even test the branch online just by typing code and
 selecting the branch! How cool would that be??

Isn't the auto-tester already doing most of this? Why not just provide a place where auto-tester-created distribution can be downloaded? -Steve

+1 It has to build DMD and Phobos anyway. Save energy, compile less! :D

Agreed.
 I would never build DMD myself to check out a pull request
 even IF I had an interest in the changes. I'm always thinking
 the QA department of DMD will check it all thoroughly.

There is no QA department, unfortunately. We are it. ;-) I have to say, though, that since I build git HEAD from source for Phobos development purposes, the easiest route for me would be to have the branch available from the official DMD repository rather than as a separate download. That way, if I want to submit patches, I can just push to github and submit a pull request -- the code would be right there. A separate download introduces two extra steps: I have to install the thing and set it up, then I have to find and checkout the correct version of the code to submit patches for. T -- Stop staring at me like that! You'll offend... no, you'll hurt your eyes!
Feb 08 2013
prev sibling next sibling parent Andrej Mitrovic <andrej.mitrovich gmail.com> writes:
On 2/7/13, Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> wrote:
 I'm very happy that this will be part of the upcoming release:
 https://github.com/D-Programming-Language/dmd/pull/1342 (see also
 http://d.puremagic.com/issues/show_bug.cgi?id=2630) allows defining
 unittests that simultaneously work as documentation. This is a great way
 to simultaneously write meaningful tests and good documentation examples.

 If you want to help, feel free to hop on the Phobos documentation and
 convert some of it to use the new feature.

There's a few bugs for which pull requests exist. Here's the state of things: https://github.com/D-Programming-Language/dmd/pull/1641 will be able to document the body of the unittest while preserving both formatting (Issue 9475) and comments (Issue 9472). However it requires Kenji's https://github.com/D-Programming-Language/dmd/pull/1377 to be pulled because it will allow me to properly unindent code samples so they line-up nicely. https://github.com/D-Programming-Language/dmd/pull/1639 will make sure each documented sample is in its own "Example:" section. https://github.com/D-Programming-Language/dmd/pull/1646 will make sure version statements don't break documented unittests. Each of these might need a rebase from my end after each one is pulled. But the most important thing is to merge Kenji's pull first so I can start work ASAP before Walter decides to release DMD.
Feb 08 2013
prev sibling next sibling parent Andrej Mitrovic <andrej.mitrovich gmail.com> writes:
On 2/8/13, Andrej Mitrovic <andrej.mitrovich gmail.com> wrote:
 There's a few bugs for which pull requests exist.

Additionally the documentation will have to be pulled: https://github.com/D-Programming-Language/d-programming-language.org/pull/264
Feb 08 2013
prev sibling next sibling parent Andrej Mitrovic <andrej.mitrovich gmail.com> writes:
On 2/7/13, Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> wrote:
 I'm very happy that this will be part of the upcoming release:
 https://github.com/D-Programming-Language/dmd/pull/1342 (see also
 http://d.puremagic.com/issues/show_bug.cgi?id=2630) allows defining
 unittests that simultaneously work as documentation. This is a great way
 to simultaneously write meaningful tests and good documentation examples.

Btw another related pull request w.r.t. documentation is this one: https://github.com/D-Programming-Language/dmd/pull/1485 It generates documentation for mixed'in code for template mixins.
Feb 08 2013
prev sibling parent Robert <jfanatiker gmx.at> writes:
On Thu, 2013-02-07 at 17:20 -0800, H. S. Teoh wrote:
 How cool would that be??

Feb 09 2013