Documentation Layout

[Jacob Carlborg]

On 2012-03-29 11:24, foobar wrote:

> 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.

I completely agree.

-- 
/Jacob Carlborg