• via Digitalmars-d-bugs (40/40) May 06 2015 https://issues.dlang.org/show_bug.cgi?id=14550

via Digitalmars-d-bugs <digitalmars-d-bugs puremagic.com> writes:

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

          Issue ID: 14550
           Summary: Ditto'ed function documentation should merge parameter
                    lists
           Product: D
           Version: D2
          Hardware: All
                OS: All
            Status: NEW
          Severity: enhancement
          Priority: P1
         Component: DMD
          Assignee: nobody puremagic.com
          Reporter: andrei erdani.com

Consider:

/**
Creates an array of $(D T) using $(D alloc). Lorem ipsum...

Params:
alloc = the allocator used for fetching memory
length = the length of the created array
init = the value used for initializing array elements
range = the range used for initializing array elements
*/
T[] makeArray(T, Allocator)(auto ref Allocator alloc, size_t length);
/// Ditto
T[] makeArray(T, Allocator)(auto ref Allocator alloc, size_t length, auto ref T
init); 
/// Ditto
T[] makeArray(T, Allocator, R)(auto ref Allocator alloc, R range) if
(isForwardRange!R); 
/// Ditto
T[] makeArray(T, Allocator, R)(auto ref Allocator alloc, R range) if
(isInputRange!R && !isForwardRange!R);

The idea here is that the parameters have disjoint names which allows the
reader to easily distinguish where each applies. That makes for compact
documentation that avoids repeating the opening (or awkwardly refer to it "like
above, but...").

Currently this setup issues warnings during compilation and lists init and
range without a type. It should "understand" and list them properly.

--