This post contains a few good considerations regarding Phobos documentation:
http://forum.dlang.org/post/[email protected]
The constraint documentation needs to be revamped - automatic generation should generate the constraint separately. For example, instead of:
auto sum(R)(R r) if (isInputRange!R && !isInfinite!R && is(typeof(r.front + r.front)));
the doc should be:
auto sum(R)(R r);
Constraint: isInputRange!R && !isInfinite!R && is(typeof(r.front + r.front))
The constraint documentation should be user-definable by means of ddoc comments embedded in the constraint. For example, if the source is:
auto sum(R)(R r)
if /** R must be a non-infinite input range and its elements should support addition. */
(isInputRange!R && !isInfinite!R && is(typeof(r.front + r.front)));
then the generated dox would be:
auto sum(R)(R r);
Constraint: R must be a non-infinite input range and its elements should support addition.
Cross-linking to key concepts such as range, ElementType etc. must be present as hot links.