• via Digitalmars-d-bugs (56/56) Nov 03 2014 https://issues.dlang.org/show_bug.cgi?id=13676

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

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

          Issue ID: 13676
           Summary: [ddoc] DDoc should wrap each part of function
                    declaration in dedicated macro to allow more readable
                    formatting
           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:

-----
$(DECLARATION
  $(RETURN_VALUE $(D CommonType!($(PARAM T), $(PARAM U)))
  $(FUNC_NAME $(D myFunc))
  $(TEMPLATE_PARAMS
    ($(PARAM $(D Flag.someOption) $(DEFAULT_VALUE $(D = Flag.someOption.yes))),
     $(PARAM $(D T)),
     $(PARAM $(D U)))
  )
  $(FUNC_PARAMS
    ($(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.

--