Documentation Layout

[foobar]

On Thursday, 29 March 2012 at 01:52:28 UTC, James Miller wrote:
> 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

Have you considered that perhaps the granularity of Phobos 
modules is too coarse? Perhaps the core issue is too many 
functions are placed in one single file without more 
consideration of their relation and organization?

Regarding the documentation system itself - it should provide as 
much automation as possible. For instance, it should be able to 
group overloads together, it should be able to group kinds 
together - types, free functions, enums, etc. it should be able 
to group together various parts of a compound type (by 
protection, by kind: constructors, properties, operators, etc. )

Given the above *and* proper organization of code - which is 
*not* the case today - an *optional* tagging system could add 
some small benefit if it's automatic. E.g add a TAG macro.

Relying on documentation before exhausting the above is IMHO 
wrong.

As others said, the documentation and code comments should 
reflect what the code itself cannot express - what is the higher 
goal we want to achieve, which  specific implementation tradeoffs 
were taken and why, etc.

breaking algorithm.d into manually maintained documentation 
"categories" clearly misses the above points.