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