[dox] List of Phobos documentation improvement candidates (Was: Re: Can we get a forum section devoted to documentation? [dox])

Andre Artus andre.artus at gmail.com
Fri Aug 16 14:23:28 PDT 2013


On Friday, 16 August 2013 at 20:03:10 UTC, H. S. Teoh wrote:
> 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

This is great, I'm busy working on some parts of the Language 
docs so I have not read through your entire list, but I have a 
short example to core.time.

There is a script running on the page you linked to that is 
making my browser misbehave. It's probably not helped by the fact 
that I have a browser tab open for every page on the interwebs.


More information about the Digitalmars-d mailing list