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

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

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

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.

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.

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

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.

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

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

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