On Fri, Aug 16, 2013 at 08:25:00PM +0200, Andre Artus wrote:
On Friday, 16 August 2013 at 18:09:04 UTC, Andrei Alexandrescu
wrote:
[...]
>Things should happen organically, i.e. creating a specialized
>group should follow a need substantiated by increased volume
>of
>specialized discussion in the general group. At this point
>there
>is nothing in that vein.
[...]
I understand were you are coming from. And, while I currently
feel
that it's a bit of a catch-22 situation, I think it is worth at
least trying out your suggestion of marking document related
threads
with "[dox]".
Alright, I'll start.
Here's a list of Phobos modules that need some documentation
facelist.
For fairness' sake, I gleaned these from:
http://dlang.org/phobos-prerelease/index.html
as opposed to the docs for the official release, so that they
closer
reflect what things will look like at the next D release.
1) The above page itself needs work. Right now it's just a very
spotty
incomplete list of seemingly-random pieces of Phobos. It looks
like the
relic from a bygone era before Phobos docs had a navbar on the
left; so
my first thought would be to kill off that incomplete module
list (leave
that to the navbar). My second thought would be to group the
modules
under more logical categories so that newbies would know which
modules
tend to be used together (e.g., std.algorithm and std.range
tend to be
used together a lot IME).
2) std.algorithm: the state of the current docs is not bad, but
could
use some improvement. The first paragraph could be expanded to
explain
what this module is all about. The part about string lambdas
(2nd
paragraph) may need to be tagged with a note about possible
deprecation,
judging from discussions in the other thread. If not, at the
very least
the code example should show how to use the new lambda syntax:
sort!((a,b) => a < b)(...);
I'm not sure what to make of the cheat sheet, as it seems to
repeat most
of the table of links at the top of the page. But maybe it's
good for
short code snippets to remind you how to use each function, so
maybe it
can be left alone for now.
3) std.array: desperately needs a more detailed explanation at
the top
to explain why this module is even needed (newbies would
wonder: doesn't
D have built-in arrays? Why do we need this module then?). Not
enough
code examples.
4) std.ascii: unhelpful description. Why do we even need this
module
when D uses UTF-8 by default? When should we use this module
and when
should we use std.uni? Also, needs an overview of what this
module
provides (string constants, character categorization, case
conversions).
5) std.base64: unhelpful description. Doesn't explain what is
base-64
and why we should care. What are the applications of base-64
anyway?
Who would want to use this stuff? Without more details, a
newcomer
wouldn't know.
6) std.bigint: badly needs more code examples, with
explanations.
7) std.bitmanip: needs more explanation about what this module
is, why
we need it, etc.. Needs categorization of what is provided
(bitfields,
endianness-related functions, anything else).
8) std.compiler: need code examples of how to use the stuff
here. Maybe
using version blocks. Maybe sample music composed in D_major...
oh wait.
Wrong forum. :-P
9) std.complex: needs more code examples. Maybe a little more
explanation about what's going on with "built-in types" and why
those
will be replaced.
10) std.concurrency: needs higher-level module description,
like what's
the use of low-level messaging systems. Need to provide
adequate context
for where/when this module should be used. Needs to link to
other doc
pages that discuss threads, processes, etc..
11) std.container: badly needs a better description. The table
of
operations with complexity guarantees needs a bit more
explanation about
what this all means. Maybe a link to somewhere (wikipedia
perhaps) that
explains the concept of complexity and why it matters. Also,
need an
overview of what containers are provided and example code on
how to use
them.
12) std.conv: the one-line description is cute, but inadequate.
Need
code examples on common usage. Need to explain in more detail
how to
make user-defined types usable with to!() (e.g., need to define
opCast,
ctor requirements, etc.). Need module overview about what's
provided
(to, octal, parse, emplace). Need code examples.
13) std.csv: Not bad, but could use an overview of module
contents with
links to each main function/struct (ala std.algorithm /
std.range).
14) std.datetime: Not bad. It would be nice to add links to
actual
functions/types in the module overview.
15) std.encoding: needs more code examples. Overview of module
contents.
16) std.exception: needs higher-level overview of what's in
this module,
with categorized functions/types. Code examples for
assertThrown & co.,
as well as explanations of why we need them.
17) std.file: needs more code examples. Module contents
overview.
18) std.format: there are a lot of good docs here, but buried in
hard-to-find places. Needs module overview, with code examples.
There
also appear to be some DDOC typos here. Especially needed is:
how to
make your own user-defined types usable with std.format. What
are the
possible hooks, example code of how they are used, etc..
19) std.functional: need more explanation of what this module
is all
about. Motivation: why do we care about functions manipulating
other
functions? There are some code examples here but could use
better
motivated examples, like when/where such features would be
useful. How
this relates to functional programming, etc..
20) std.getopt: not bad. Maybe add some examples of an actual
shell
session and how getopt parses things. Explain what args[0]
means (this
is very non-obvious to people unfamiliar with command-line
UIs!).
21) std.json: needs proper description and code examples.
22) std.math: needs categorized summary of module contents.
23) std.mathspecial: needs code examples. Explanation of why
this isn't
part of std.math.
24) std.mmfile: needs a LOT of explanation of what this is, and
why it
might be useful. Code examples.
25) std.numeric: needs adequate explanation of what this module
does and
why it's needed. Why isn't it part of std.math, what's the
difference,
etc.. Categorized summary of module contents.
26) std.outbuffer: needs explanation of what this module is.
Code
examples.
27) std.parallelism: not bad. A linked overview of module
contents would
be nice.
28) std.path: needs linked overview of module contents. Why
this isn't
part of std.file. In fact, the Phobos index page should group
std.file,
std.stdio, and std.path together, and explain what's the
difference
between them, and what each module covers in terms of
file-related
operations.
29) std.process: pretty good! Maybe explain how this relates to
std.parallelism, std.concurrency, etc.. The difference may not
be
obvious to newcomers. Possibly put this explanation in the
Phobos index
page.
30) std.random: linked overview of module contents would be
nice. More
code examples. Maybe a brief discussion on various RNG issues,
like
measure of randomness, reproducible/non-reproducible sequences,
cryptographic strength, etc..
31) std.range: not bad (if I say so myself ;-P). More code
examples
would be nice. As well as motivating examples of when you might
want to
use each range type.
32) std.regex: pretty good!
33) std.signals: ugly. The links to various forum discussion
threads is
a poor substitute for a well-written summary of the contents of
said
discussions. Needs more code examples and applications.
34) std.socket: needs a module description!! And many more code
examples. And module contents overview.
35) std.socketstream: not sure if we want to spend more effort
documenting this, since it's slated for replacement, but might
not hurt
in the short term to do so.
36) std.stdio: very unhelpful description. Should explain
exactly what
this module does for people who *don't* know C, what types /
functions
it exports, code examples of how to use them. E.g., how to open
/ close
a file, how to read/write text data, how to read/write binary
data.
Explain range interface for files. Caveats on the transience of
byLine.
37) std.cstream, std.stream: not sure how much to do for these,
since
they're slated for replacement.
38) std.string: need better description. Why this module exists
(aren't
strings built-in in D?), what it provides (linked overview of
contents),
more code examples.
39) std.system: explain what this module is, why we need it,
when it
should be used. Code examples (*motivating* code examples, not
just
random code snippets that happens to use the symbols exported
here!).
This should be grouped with std.compiler in the Phobos index
page.
40) std.traits: need to elaborate on description. Brief
discussion of
metaprogramming maybe? With motivating code examples. Need
linked
overview of contents. There's a lot of stuff in here; grouping
into
logical categories should be more helpful.
41) std.typecons: need better description. Explain basic usage,
what it
means, etc.. The current code example is rather abstruse to a
newcomer;
needs more down-to-earth explanations of what exactly is going
on in the
code. Needs overview of contents. More code examples. Things
like Flag
should be highlighted so that newbies pick up on the concept
and use
Flag instead of bools everywhere.
42) std.typetuple: need proper explanation of the difference
between
TypeTuple, std.range.Tuple, and compile-time "tuples"
(SymbolTuples, as
Ali calls them). This is very confusing for newbies (and even
for
experienced D coders!). Overview of module contents.
43) std.uni: I think Dmitry's new std.uni hasn't been updated on
dlang.org yet, so I'll refrain from commenting for now. From
what I
remember, the new docs (and code, of course!) are far better
than the
one you see on dlang.org, so probably we don't have to worry
about it.
44) std.uri: the description could use some elaboration. And
code
examples.
45) std.utf: need to elaborate description. How this relates to
std.uni.
Example code. Issues to deal with when interfacing with C code
(toUTF*z).
46) std.uuid: not bad!
47) std.variant: not bad. Could use more code examples in a few
places.
Maybe higher-level discussion of usage, motivation, potential
issues,
etc.. Overview of module contents.
48) std.xml: slated for replacement; so just let be for now?
49) std.zip: Need better module description, overview of
contents. How
this relates to std.zlib.
50) std.zlib: why this isn't part of std.zip. Code examples!!
51) std.net.curl: not bad.
52) std.net.isemail: need code examples!
53) std.digest.*: not bad! Phobos index page needs to group
these
together and explain how each piece relates to the others.
54) std.windows.charset: explain why this isn't part of
std.encoding.
Code examples. (Also, why is the CSS broken for this page on
dlang.org?)
Phew, I never realized Phobos was *this* big! This covers only
std.*,
but there's still etc.* and core.*. Lots of work ahead of us!
T
