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.
