www.digitalmars.com         C & C++   DMDScript  

digitalmars.D - Phobos Documentation - call to action

reply Walter Bright <newshound2 digitalmars.com> writes:
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.
Mar 17 2015
next sibling parent reply "Zach the Mystic" <reachzach gggmail.com> writes:
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.
No responses yet -- not that I'm any less guilty than anyone else. But maybe this needs to be bumped up to a higher priority -- a hiatus on internal development for a couple weeks solely to bring documentation up to a minimum. Obviously clear guidelines like the ones you just posted are a plus.
Mar 18 2015
parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 3/18/2015 10:55 AM, Zach the Mystic wrote:
 No responses yet -- not that I'm any less guilty than anyone else. But maybe
 this needs to be bumped up to a higher priority -- a hiatus on internal
 development for a couple weeks solely to bring documentation up to a minimum.
 Obviously clear guidelines like the ones you just posted are a plus.
We have a great language, but represent it poorly in the documentation. Every library entry also needs a pithy example (or even any example at all), but I thought we could make progress first by simply documenting what the return value is supposed to be. We also need to stop pulling new library additions that have obviously inadequate documentation.
Mar 18 2015
parent reply "Zach the Mystic" <reachzach gggmail.com> writes:
On Wednesday, 18 March 2015 at 18:09:07 UTC, Walter Bright wrote:
 On 3/18/2015 10:55 AM, Zach the Mystic wrote:
 No responses yet -- not that I'm any less guilty than anyone 
 else. But maybe
 this needs to be bumped up to a higher priority -- a hiatus on 
 internal
 development for a couple weeks solely to bring documentation 
 up to a minimum.
 Obviously clear guidelines like the ones you just posted are a 
 plus.
We have a great language, but represent it poorly in the documentation. Every library entry also needs a pithy example (or even any example at all), but I thought we could make progress first by simply documenting what the return value is supposed to be. We also need to stop pulling new library additions that have obviously inadequate documentation.
I'm just thinking in terms of psychology. I haven't seen anyone disagree that the documentation is inadequate, so that's not even disputed. But why, therefore, is it so hard to get movement on it? I suspect that it's because it is perceived as a chore, like cleaning a barn. I don't want to go in that barn by myself. But if I everyone's doing it, with the mutual understanding that it needs to get done - and no one is exempt - then it doesn't feel so bad. At some point, it must be possible for documentation to get so bad that *nothing* is more important. Otherwise, it may well continue to flounder in destitute obscurity, never receiving the attention it deserves.
Mar 18 2015
next sibling parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
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
Mar 18 2015
next sibling parent "Zach the Mystic" <reachzach gggmail.com> writes:
On Wednesday, 18 March 2015 at 19:50:24 UTC, 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).
Yeah, it appears so.
 A body of examples of idiomatic uses of the language is missing.
Unfortunately, I get the sense that's not the only thing that's missing. Full disclosure: I'm not an experienced team leader, so I can't promise my suggestion will work. That said, I suggest, for the purpose of turning motive into action, a ten-day "Documentation Holiday", akin to Franklin D. Roosevelt's "Bank Holiday" of 1933: http://en.wikipedia.org/wiki/Emergency_Banking_Act Guidelines for enhancements must be drawn up and made clear in advance, and the community given sufficient notice to prepare for the "holiday". It's just an idea... but as you say, D is already there, strategically. I didn't feel great about having to be the first to respond to this thread, since I'm not a major contributor (yet, anyway) - it looks like the sign of a real problem.
Mar 18 2015
prev sibling parent Rikki Cattermole <alphaglosined gmail.com> writes:
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.
Mar 18 2015
prev sibling parent reply Walter Bright <newshound2 digitalmars.com> writes:
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? :-)
Mar 18 2015
next sibling parent "H. S. Teoh via Digitalmars-d" <digitalmars-d puremagic.com> writes:
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 More will come. I'm so sick of talking about problems without doing anything, and talking about "talking about problems without doing anything" without doing anything. T -- Nothing in the world is more distasteful to a man than to take the path that leads to himself. -- Herman Hesse
Mar 18 2015
prev sibling next sibling parent reply "H. S. Teoh via Digitalmars-d" <digitalmars-d puremagic.com> writes:
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 T -- MAS = Mana Ada Sistem?
Mar 18 2015
parent Walter Bright <newshound2 digitalmars.com> writes:
On 3/18/2015 1:27 PM, 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
You da man, H.S. !
Mar 18 2015
prev sibling next sibling parent reply "Zach the Mystic" <reachzach gggmail.com> writes:
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.
Mar 18 2015
parent reply "H. S. Teoh via Digitalmars-d" <digitalmars-d puremagic.com> writes:
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
Mar 18 2015
parent Walter Bright <newshound2 digitalmars.com> writes:
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.
Mar 19 2015
prev sibling parent "H. S. Teoh via Digitalmars-d" <digitalmars-d puremagic.com> writes:
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"...
Mar 18 2015
prev sibling next sibling parent "Kagamin" <spam here.lot> writes:
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.
Mar 19 2015
prev sibling next sibling parent reply "Jesse Phillips" <Jesse.K.Phillips+D gmail.com> writes:
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.
Mar 20 2015
parent reply Walter Bright <newshound2 digitalmars.com> writes:
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.
Mar 20 2015
parent reply "H. S. Teoh via Digitalmars-d" <digitalmars-d puremagic.com> writes:
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
Mar 20 2015
parent Walter Bright <newshound2 digitalmars.com> writes:
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.
Mar 20 2015
prev sibling next sibling parent reply "Joseph Rushton Wakeling" <joseph.wakeling webdrake.net> writes:
On Wednesday, 18 March 2015 at 03:45:07 UTC, Walter Bright wrote:
 1. The sections Params, Returns, and See_Also need to be there. 
 (Unless there are no parameters, or a void return.)
Any chance of getting a TemplateParams: (or Template_Params:) option in the next dmd release, too? Would help very much with documenting ranges. What in particular do you want in the See_Also? I'd have assumed it was only necessary for a subset of methods.
 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.
I'll see what I can do :-)
Mar 21 2015
parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 3/21/2015 1:00 AM, Joseph Rushton Wakeling wrote:
 On Wednesday, 18 March 2015 at 03:45:07 UTC, Walter Bright wrote:
 1. The sections Params, Returns, and See_Also need to be there. (Unless there
 are no parameters, or a void return.)
Any chance of getting a TemplateParams: (or Template_Params:) option in the next dmd release, too? Would help very much with documenting ranges.
Just put them in Params:.
 What in particular do you want in the See_Also? I'd have assumed it was only
necessary for a subset of methods.
Functions that do something similar in case the function is not quite what they're looking for, along with other functions that are likely to be needed with it.
 3. Resist the urge to do more, stay focused simply on filling in the blanks,
 one PR per function, making things easy to review.
I'll see what I can do :-)
Thank you!
Mar 21 2015
parent reply "Joseph Rushton Wakeling" <joseph.wakeling webdrake.net> writes:
On Saturday, 21 March 2015 at 08:24:42 UTC, Walter Bright wrote:
 Any chance of getting a TemplateParams: (or Template_Params:) 
 option in the next
 dmd release, too?  Would help very much with documenting 
 ranges.
Just put them in Params:.
Yeah, I'm not going to let it block contributing to this call for action. But I would still like to have a separate TemplateParams for future (and personal project) use. No promises, but if you can give me a pointer or two as to how that might be implemented, I'd consider having a look at doing it myself.
Mar 22 2015
parent Walter Bright <newshound2 digitalmars.com> writes:
On 3/22/2015 7:21 AM, Joseph Rushton Wakeling wrote:
 No promises, but if you can give me a pointer or two as to how that might be
 implemented, I'd consider having a look at doing it myself.
It would be copy/paste of the code that implements Params: But I don't see the added value for it, and probably would not pull it without a compelling rationale.
Mar 22 2015
prev sibling parent Walter Bright <newshound2 digitalmars.com> writes:
Thanks to everyone who has been filing pull requests on this!
Mar 22 2015