• Andrei Alexandrescu (9/9) Feb 07 2013 I'm very happy that this will be part of the upcoming release:
• H. S. Teoh (12/21) Feb 07 2013 [...]
• Andrei Alexandrescu (3/8) Feb 07 2013 Agreed on both. Andrej?
• H. S. Teoh (8/17) Feb 07 2013 [...]
• H. S. Teoh (8/23) Feb 07 2013 [...]
• H. S. Teoh (10/31) Feb 07 2013 [...]
• Marco Leise (7/14) Feb 07 2013 That's totally legit to report. I also want that feature to
• Andrej Mitrovic (4/7) Feb 07 2013 This is why we desperately need a way for users to test out new
• H. S. Teoh (23/32) Feb 07 2013 Maybe feature branches are what we need for this?
• Steven Schveighoffer (5/9) Feb 07 2013 Isn't the auto-tester already doing most of this? Why not just provide ...
• Marco Leise (10/23) Feb 07 2013 +1
• H. S. Teoh (15/38) Feb 08 2013 [...]
• Marco Leise (13/13) Feb 07 2013 The next step could be to document function parameters inline.
• Chad Joan (3/12) Feb 07 2013 YES YES YES. YES. YES>
• Andrej Mitrovic (15/22) Feb 08 2013 There's a few bugs for which pull requests exist. Here's the state of th...
• Andrej Mitrovic (3/4) Feb 08 2013 Additionally the documentation will have to be pulled:
• Andrej Mitrovic (4/9) Feb 08 2013 Btw another related pull request w.r.t. documentation is this one:
• Robert (2/3) Feb 09 2013 Awesome!

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

"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

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

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

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

"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

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

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.

"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

"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

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

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

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

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.

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.

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

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.

Robert <jfanatiker gmx.at> writes:

On Thu, 2013-02-07 at 17:20 -0800, H. S. Teoh wrote:
 How cool would that be??

Awesome!