Review of Jose Armando Garcia Sancio's std.log

[David Gileadi]

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.