On 19/03/2015 8:50 a.m., Andrei Alexandrescu wrote:
> On 3/18/15 12:42 PM, Zach the Mystic wrote:
>> At some point, it must be possible for documentation to get so bad that
>> *nothing* is more important.
>
> Strategically we're definitely there, and have been for a while (if we
> define improving D's rate of adoption as important).
>
> An anecdote: at work I'm making a pass through D code written by a few
> coworkers - all brilliant engineers. They come from various backgrounds
> (Python, Java, C++, Go) and it's no surprise that there's a bunch of
> these langauages' typical idioms redone in D. This (especially due to
> the Java and Go influence) makes the code very pedestrian, to the point
> there's no visible advantage to D over these languages. You may as well
> translate it to them with little trouble, and word has come about about
> such.
>
> A body of examples of idiomatic uses of the language is missing. I
> speculate many people who take a look at D find it difficult to see
> (using the material we provide) how it outdoes its competition.
>
>
> Andrei

So in other words we either need a page, or a group of pages on the main site dedicated to idioms and how to use them.

On Wednesday, 18 March 2015 at 20:19:10 UTC, Walter Bright wrote:
> On 3/18/2015 12:42 PM, Zach the Mystic wrote:
>> But why, therefore, is it so hard to get movement on it?
>
> I don't know why, so I'll ask. Why haven't you submitted a PR to fix one of them? :-)

I have pathetically little experience with most of phobos. I most certainly hold the record for amount of passion associated with the D language versus number of lines actually coded in it. That said, it can't be that hard to figure out what the parameters are and what they return. If you give me a specific module, I'll start making pull requests for it.

On Thu, Mar 19, 2015 at 02:51:12AM +0000, Zach the Mystic via Digitalmars-d wrote:
> On Wednesday, 18 March 2015 at 20:19:10 UTC, Walter Bright wrote:
> >On 3/18/2015 12:42 PM, Zach the Mystic wrote:
> >>But why, therefore, is it so hard to get movement on it?
> >
> >I don't know why, so I'll ask. Why haven't you submitted a PR to fix one of them? :-)
> 
> I have pathetically little experience with most of phobos. I most certainly hold the record for amount of passion associated with the D language versus number of lines actually coded in it. That said, it can't be that hard to figure out what the parameters are and what they return. If you give me a specific module, I'll start making pull requests for it.

What about just picking a random Phobos module from dlang.org and scrolling through to find an undocumented (or poorly-documented) function? There are sadly a *lot* of such modules in Phobos; it won't be long before you find something.


T

-- 
If you look at a thing nine hundred and ninety-nine times, you are perfectly safe; if you look at it the thousandth time, you are in frightful danger of seeing it for the first time. -- G. K. Chesterton

On Wed, Mar 18, 2015 at 01:27:53PM -0700, H. S. Teoh via Digitalmars-d wrote:
> On Wed, Mar 18, 2015 at 01:23:26PM -0700, H. S. Teoh via Digitalmars-d wrote:
> > On Wed, Mar 18, 2015 at 01:18:41PM -0700, Walter Bright via Digitalmars-d wrote:
> > > On 3/18/2015 12:42 PM, Zach the Mystic wrote:
> > > >But why, therefore, is it so hard to get movement on it?
> > > 
> > > I don't know why, so I'll ask. Why haven't you submitted a PR to fix one of them? :-)
> > 
> > Argh, so much hot air on the forum, so little action. This is getting so tiresome. Let's kickstart some *real* action here:
> > 
> > 	https://github.com/D-Programming-Language/phobos/pull/3063
> [...]
> 
> https://github.com/D-Programming-Language/phobos/pull/3064
[...]

A little speedbump: recent dlang.org changes broke the 'html' target of the Phobos makefile, so that the new-fangled collapsible navbar doesn't get rendered into the html. While this isn't a showstopper, it does make it more annoying to locally test doc-related PR's, so it would be nice if somebody could review and pull the fix:

	https://github.com/D-Programming-Language/phobos/pull/3067


T

-- 
I'm still trying to find a pun for "punishment"...

Two low-hanging fruits are to document bug https://issues.dlang.org/show_bug.cgi?id=2742 (phobos) and https://issues.dlang.org/show_bug.cgi?id=1983 (language)
Only two lines in docs.

On 3/18/2015 8:17 PM, H. S. Teoh via Digitalmars-d wrote:
>> I have pathetically little experience with most of phobos. I most
>> certainly hold the record for amount of passion associated with the D
>> language versus number of lines actually coded in it. That said, it
>> can't be that hard to figure out what the parameters are and what they
>> return. If you give me a specific module, I'll start making pull
>> requests for it.
>
> What about just picking a random Phobos module from dlang.org and
> scrolling through to find an undocumented (or poorly-documented)
> function? There are sadly a *lot* of such modules in Phobos; it won't be
> long before you find something.


True, I find them everywhere I look.

On Wednesday, 18 March 2015 at 03:45:07 UTC, Walter Bright wrote:
> The bad news: the Phobos documentation sux.
>
> The good news: we can make things a lot better by just filling in blanks. For example, picking a function largely at random:
>
>   http://dlang.org/phobos/std_uni.html#sicmp
>
> There is no Params section, no Returns: section, and no See_Also section. Hence, I wrote a PR for it:
>
>   https://github.com/D-Programming-Language/phobos/pull/3060
>
> There's nothing clever about it, just filling in the blanks. If we all pitch in, we can substantially improve the documentation.
>
> Some guidelines:
>
> 1. The sections Params, Returns, and See_Also need to be there. (Unless there are no parameters, or a void return.)
>
> 2. One PR per function being fixed.
>
> 3. Resist the urge to do more, stay focused simply on filling in the blanks, one PR per function, making things easy to review.

Can I do this and not feel bad for not setting up and running unittests/generating docs (maybe because I just used the GitHub built in text editor)? Could unittest example blocks be added which are tested outside, but weren't tested once copied into the file?

I'm not against these things, but it may be easier to find time when testing/verifying changes within the system can't be done.

On 3/20/2015 5:56 PM, Jesse Phillips wrote:
> Can I do this and not feel bad for not setting up and running
> unittests/generating docs (maybe because I just used the GitHub built in text
> editor)? Could unittest example blocks be added which are tested outside, but
> weren't tested once copied into the file?

The autotester will run all the unittests. It's ok if you plan on fixing autotest failures in a timely manner.

On Fri, Mar 20, 2015 at 06:58:38PM -0700, Walter Bright via Digitalmars-d wrote:
> On 3/20/2015 5:56 PM, Jesse Phillips wrote:
> >Can I do this and not feel bad for not setting up and running unittests/generating docs (maybe because I just used the GitHub built in text editor)? Could unittest example blocks be added which are tested outside, but weren't tested once copied into the file?
> 
> The autotester will run all the unittests. It's ok if you plan on fixing autotest failures in a timely manner.

You could run the unittests of a single module individually:

	dmd -main -unittest std/algorithm/iteration.d -of/tmp/test && /tmp/test

I do this all the time because Phobos unittests take too long to run while I'm still working on the code.


T

-- 
The best compiler is between your ears. -- Michael Abrash

On 3/20/2015 10:23 PM, H. S. Teoh via Digitalmars-d wrote:
> On Fri, Mar 20, 2015 at 06:58:38PM -0700, Walter Bright via Digitalmars-d wrote:
>> The autotester will run all the unittests. It's ok if you plan on
>> fixing autotest failures in a timely manner.
>
> You could run the unittests of a single module individually:
>
> 	dmd -main -unittest std/algorithm/iteration.d -of/tmp/test && /tmp/test
>
> I do this all the time because Phobos unittests take too long to run
> while I'm still working on the code.

Yup, I do that too. Except I use -cov, too, to check that the unittests are actually testing the code.