On 3/6/12 5:39 PM, H. S. Teoh wrote:
I don't like the current state of dlang.org docs either. There is little
or no intro paragraph to explain what on earth the module is used for or
why you should bother reading the rest of the page for the next hour or
so. It also doesn't give any motivating examples (I'm thinking of
std.range here) why this module is useful.

I think a good intro is a must to good documentation. Include some code
snippets to show typical usage of the module. How to change common
settings. Some explanation of why the user might find the module
helpful. It's OK to duplicate some docs here, within reason. It should
also be concise without being uninformative.

For example (from std.range):

        This module defines the notion of range (by the membership tests
        isInputRange, isForwardRange, isBidirectionalRange,
        isRandomAccessRange), range capability tests (such as hasLength
        or hasSlicing), and a few useful range incarnations.

is concise, but not very informative. Why should the user care what a
range is anyway? No explanation is given. Something like this may be a
beginning to better documentation:

        This module defines the notion of a range. Ranges generalize the
        concept of arrays, lists, or anything that involves sequential
        access. This abstraction enables the same set of algorithms (see
        std.algorithm) to be used with a vast variety of different
        concrete types. For example, a linear search algorithm such as
        std.find works not just for arrays, but for linked-lists, input
        files, incoming network data, etc..

        This module defines several templates (<!--insert list
        here-->)for testing whether a given object is a range, and what
        kind of range it is.

        It also lets you construct new ranges out of existing ranges.
        For example, retro lets you access a bidirectional range in
        reverse, cycle creates a range that is an endless repetition of
        the original range. ...

        ...

Basically, you're writing an overview to the module, so highlight its
main components, give some insight into why it's useful, etc., so that
the user can make sense of the long list of declarations that follow.

As it stands, std.range's page consists of a giant list of range-related
declarations that gives no hint to the user as to how they all fit
together. You basically have to wade through it until it somehow all
"clicks" together. That is poor documentation. The overview should give
some general categories of stuff that's found in the module (e.g. range
tests, constructing new ranges, etc., as I've tried to do above in my
one-shot attempt to improve std.range's docs). Include some examples of
really clever stuff that you can do with the help of the module. Such
examples are usually a very good way to get the user up-to-speed with
what the module has to offer.

I strongly agree, particularly in the case of ranges which are not a familiar concept to many, but also with the general principle.

Reply via email to