[Issue 13676] [ddoc] DDoc should wrap each part of function declaration in dedicated macro to allow more readable formatting

Dec 19, 2014

hsteoh@quickfur.ath.cx

Dec 27, 2014

bearophile_hugs@eml.cc

Dec 15, 2015

Dec 15, 2015

Dec 15, 2015

Dec 15, 2015

Dec 24, 2015

Dec 23, 2016

Dec 17, 2022

Dec 13

dlangBugzillaToGithub

https://issues.dlang.org/show_bug.cgi?id=13676 hsteoh@quickfur.ath.cx changed: What |Removed |Added ---------------------------------------------------------------------------- See Also| |https://issues.dlang.org/sh | |ow_bug.cgi?id=13863 --

December 27, 2014

[Issue 13676] [ddoc] DDoc should wrap each part of function declaration in dedicated macro to allow more readable formatting

Posted by bearophile_hugs@eml.cc

Permalink

bearophile_hugs@eml.cc

Permalink

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

bearophile_hugs@eml.cc changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
                 CC|                            |bearophile_hugs@eml.cc

--- Comment #1 from bearophile_hugs@eml.cc ---
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.

--

https://issues.dlang.org/show_bug.cgi?id=13676 Andrei Alexandrescu <andrei@erdani.com> changed: What |Removed |Added ---------------------------------------------------------------------------- CC| |andrei@erdani.com --

https://issues.dlang.org/show_bug.cgi?id=13676 ZombineDev <petar.p.kirov@gmail.com> changed: What |Removed |Added ---------------------------------------------------------------------------- Keywords| |preapproved CC| |petar.p.kirov@gmail.com --- Comment #2 from ZombineDev <petar.p.kirov@gmail.com> --- Andrei preapproved this enhancement: http://forum.dlang.org/post/n4o22t$r48$1@digitalmars.com --

https://issues.dlang.org/show_bug.cgi?id=13676 landaire <landergriffith+dlangbz@gmail.com> changed: What |Removed |Added ---------------------------------------------------------------------------- CC| |landergriffith+dlangbz@gmai | |l.com --- Comment #3 from landaire <landergriffith+dlangbz@gmail.com> --- Jack Stouffer suggested I add my (visual) suggestions here: http://imgur.com/a/njHKI Context: http://forum.dlang.org/post/ckmfubbgppizescgjkli@forum.dlang.org --

https://issues.dlang.org/show_bug.cgi?id=13676 --- Comment #4 from landaire <landergriffith+dlangbz@gmail.com> --- 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. --

https://issues.dlang.org/show_bug.cgi?id=13676 --- Comment #5 from landaire <landergriffith+dlangbz@gmail.com> --- 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. --

https://issues.dlang.org/show_bug.cgi?id=13676 greenify <greeenify@gmail.com> changed: What |Removed |Added ---------------------------------------------------------------------------- CC| |greeenify@gmail.com --- Comment #6 from greenify <greeenify@gmail.com> --- > - 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. --

https://issues.dlang.org/show_bug.cgi?id=13676 Iain Buclaw <ibuclaw@gdcproject.org> changed: What |Removed |Added ---------------------------------------------------------------------------- Priority|P1 |P4 --

https://issues.dlang.org/show_bug.cgi?id=13676 --- Comment #7 from dlangBugzillaToGithub <robert.schadek@posteo.de> --- THIS ISSUE HAS BEEN MOVED TO GITHUB https://github.com/dlang/dmd/issues/18903 DO NOT COMMENT HERE ANYMORE, NOBODY WILL SEE IT, THIS ISSUE HAS BEEN MOVED TO GITHUB --

Forums