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.
Comment #1 by bearophile_hugs — 2014-12-27T11:56:34Z
In Scala they have added the @usecase annotation to face this problem:
https://wiki.scala-lang.org/display/SW/Tags+and+Annotations
From that page:
@usecase <simple definition> In case the method definition is too complex, you can add simple aliasing definition as a usecase. It will create another entry in the scaladoc page as if the <simple definition> actually existed. The description for the newly created entry is the same as the one for the current symbol, just that it's preceded by [use case] to signal it's not a real entry. An example can be seen in the ++ method of scala.collections.immutable.Set.
Elsewhere there is written:
the usecases inherit the comments from their parents, such as the explanation and the annotations: @param, @tparam, @return, etc.
Comment #2 by petar.p.kirov — 2015-12-15T09:39:10Z
Comment #4 by landergriffith+dlangbz — 2015-12-15T16:54:55Z
Also might as well copy my other suggestions:
- Inline runnable examples: They're present on the homepage, why can't the examples provided in the inline docs be runnable as well?
- Link to where the code is implemented in Phobos at the time of compilation. e.g. clicking the name of the function "find" when looking at the signature could link me here: https://github.com/D-Programming-Language/phobos/blob/b6a61d9e719a9d680936db44b98fbb5dd28bf6b1/std/algorithm/searching.d#L1498. More than once I found that reading the code was more useful than reading the documentation.
Comment #5 by landergriffith+dlangbz — 2015-12-24T02:54:59Z
I want to note that I've done a little bit of work on this here: https://github.com/D-Programming-Language/dmd/pull/5311
- Add function overload separator macro
- Add template constraint macro
- Add template param list macro
- Add template param macro
All related parts of function signatures are wrapped in their respective macros.
Comment #6 by greeenify — 2016-12-23T01:14:35Z
> - Inline runnable examples: They're present on the homepage, why can't the examples provided in the inline docs be runnable as well?
We have this in preview mode now:
https://github.com/dlang/dlang.org/pull/1297
> Link to where the code is implemented in Phobos at the time of compilation. e.g. clicking the name of the function "find" when looking at the signature could link me here
Yeah that would be pretty awesome.
Comment #7 by robert.schadek — 2024-12-13T18:32:22Z