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.
