[Issue 13901] New: Improvements to documentation

[via Digitalmars-d-bugs]

https://issues.dlang.org/show_bug.cgi?id=13901

          Issue ID: 13901
           Summary: Improvements to documentation
           Product: D
           Version: D2
          Hardware: x86
                OS: Mac OS X
            Status: NEW
          Severity: enhancement
          Priority: P1
         Component: Phobos
          Assignee: nobody at puremagic.com
          Reporter: andrei at erdani.com

This post contains a few good considerations regarding Phobos documentation:

http://forum.dlang.org/post/wwonahubwyixrseqbrpq@forum.dlang.org

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.

--