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
