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

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.

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

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!

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.

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

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.

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