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

Jack Stouffer <jack@jackstouffer.com> changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
           Keywords|                            |ddoc

--

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

Jakob Ovrum <jakobovrum@gmail.com> changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
                 CC|                            |jakobovrum@gmail.com

--- Comment #1 from Jakob Ovrum <jakobovrum@gmail.com> ---
(In reply to Jack Stouffer from comment #0)
> Currently, as function templates are auto attributed, there is no way to know if a template is nothrow, pure, @nogc, or @safe without trying to run it in your code and seeing if it will compile. That sucks and is tedious.
> 
> So what this bug report is proposing is to add a new section in ddoc headers that allows maintainers of phobos to very visually show what attributes the template will have with what arguments.
> 
> Sure, sometimes the documentation will say that if the template is @nogc or not, but not all the time.
> 
> Also, this answers a common question new comers have, which is "doesn't the std lib use the GC?" To which the response is "Not all of it". To which the follow up is "Ok, what parts use it and what parts don't?", followed by crickets.

DDoc section can be added arbitrarily with any name, there are no restrictions on them, except a few of them get special handling like `Params`.

Does the proposed section need any special handling? If not, this isn't a DMD issue.

--

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

--- Comment #2 from Jack Stouffer <jack@jackstouffer.com> ---
I was thinking of a tabular format, like "given these types of inputs it has these attributes".

--

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

--- Comment #3 from Jakob Ovrum <jakobovrum@gmail.com> ---
(In reply to Jack Stouffer from comment #2)
> I was thinking of a tabular format, like "given these types of inputs it has these attributes".

We can do that without special syntax. I think we should only consider special syntax if we can't figure out a nice way to do it with regular DDoc macros, and considering our previous experience in expressing tabular data with DDoc, I'd consider that unlikely. See for example the table indexes for the std.algorithm modules.

--

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

Steven Schveighoffer <schveiguy@yahoo.com> changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
                 CC|                            |schveiguy@yahoo.com

--- Comment #4 from Steven Schveighoffer <schveiguy@yahoo.com> ---
A template's inferred attributes can change with the wind, if something it calls changes, or something passed changes. This would be a maintenance nightmare if it's manually updated.

What I would suggest is possibly in examples, the compiler can add an additional comment when generating ddoc of what attributes were inferred.

In other words, you could put:

foo(a, b, c) // sig...

where the compiler would allow a click on "sig..." to show the full signature of foo used by this call.

This would also be backwards compatible (albeit confusing)

--

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

Iain Buclaw <ibuclaw@gdcproject.org> changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
           Priority|P1                          |P4

--

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

--- Comment #5 from dlangBugzillaToGithub <robert.schadek@posteo.de> ---
THIS ISSUE HAS BEEN MOVED TO GITHUB

https://github.com/dlang/dmd/issues/19046

DO NOT COMMENT HERE ANYMORE, NOBODY WILL SEE IT, THIS ISSUE HAS BEEN MOVED TO GITHUB

--