Documentation Layout

[James Miller]

On 29 March 2012 13:58, Nathan M. Swan <nathanmswan at gmail.com> wrote:
> On Wednesday, 28 March 2012 at 22:43:19 UTC, foobar wrote:
>>
>> Categories - worst idea ever.
>>
>> What's better:
>> int a; // this is size
>> OR
>> int size;
>>
>> Same thing applies here - code MUST be self documenting as much as
>> possible.
>
>
> But categories are still useful, e.g., when you want a function in
> std.algorithm that looks for a specific element. It could be "search" or
> "find" or "firstElemSatisfyingCondition", and even though those are all self
> documenting, it would be a pain to look through the list of functions in
> alphabetical order. The use of categories narrows your search for the
> function down 20%.
>
> NMS

Exactly my point. There is a line between "code must be self
documenting" and "I need to read the code to understand what this
does". Self documenting code is more about removing the cognitive
stress of reading code. Actual documentation needs the whys and
wherefores about everything.

std.string is a brilliant example, with a list of 68 functions at the
top, and a total of 89 anchors (presumably just overloads), there is
no easy way to quickly find a function for a purpose. You have indexOf
- a searching function - next to insert - a manipulation function -
next to isNumeric - a property testing function. Each of those
functions are "self-documenting" but that doesn't mean they wouldn't
benefit from categorization.

--
James Miller