www.digitalmars.com         C & C++   DMDScript  

digitalmars.D.bugs - [Issue 13676] New: [ddoc] DDoc should wrap each part of function


          Issue ID: 13676
           Summary: [ddoc] DDoc should wrap each part of function
                    declaration in dedicated macro to allow more readable
           Product: D
           Version: D2
          Hardware: All
                OS: All
            Status: NEW
          Severity: enhancement
          Priority: P1
         Component: DMD
          Assignee: nobody puremagic.com
          Reporter: hsteoh quickfur.ath.cx

Currently, a long function declaration with long template arguments, long
parameters, and long multi-clause signature contraints produces an unreadable
dense blob of text in the output with no way to control the formatting in a
finer-grained way.

Ideally, ddoc should wrap each part of the declaration around an appropriate
macro. For example:
CommonType!(T,U) myFunc(Flag.someOption = Flag.someOption.yes, T, U)(T t, U u)
 nogc nothrow pure
if (isInputRange!T && isOutputRange!(U, int))
in { assert(u.init < t.init); }
out(CommonType!(T,U) ret) { assert(ret * ret < u.init); }
body {...}

should expand to a series of macros wrapping around each part of the
declaration to permit easier customization:

  $(RETURN_VALUE $(D CommonType!($(PARAM T), $(PARAM U)))
  $(FUNC_NAME $(D myFunc))
    ($(PARAM $(D Flag.someOption) $(DEFAULT_VALUE $(D = Flag.someOption.yes))),
     $(PARAM $(D T)),
     $(PARAM $(D U)))
    ($(PARAM $(D T t),)
     $(PARAM $(D U u))
  $(FUNC_ATTRS $(D  nogc) $(D nothrow) $(D pure))
  $(SIG_CONSTRAINT $(D if (isInputRange!T && isOutputRange!(U, int))))
  $(IN_CONTRACT $(D in { assert(u.init < t.init); }))
  $(OUT_CONTRACT $(D out($(PARAM CommonType!(T,U))) { assert(ret * ret <
u.init); }))

This way, there's the possibility of grouping and styling things in a more
readable way than we can right now.

Nov 03 2014