Support STD-like "Throws:" clause

[akrzemi1]

In the C++ Standard library specification it is customary to say:

Throws: Nothing.

Which means "this function throws nothing if preconditions are satisfied" (otherwise it is free to throw).

And:

Throws: Any exception thrown by the selected constructor of T.

Which makes more sense than a table, in case of function templates.

Can you add support for this? Even if it means a different marker, such as @stdthrows.

[alandefreitas]

What’s the proposed syntax? It would be a shortcut for something achievable with @throws?

[akrzemi1]

I understand that the present @throws is eager to draw a table of type-description pairs.

I propose something like ordinary text:

/**
  @stdthrows Whatever the selected constructor of `T` throws.
 */

[alandefreitas]

Mmmm... So https://www.doxygen.nl/manual/commands.html#cmdthrow without the <exception-object>

[akrzemi1]

In a way, yes.

[alandefreitas]

What about something like

https://github.com/boostorg/url/blob/b6688d9fbb47fa917a294022c443af40e0c8d7ca/include/boost/url/pct_string_view.hpp#L114-L115

        @par Exception Safety
        Throws nothing.

[alandefreitas]

Another discussion: https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2020/p1656r1.html

[alandefreitas]

Or maybe what we need are shortcuts to https://en.cppreference.com/w/cpp/language/exceptions#Exception_safety

[akrzemi1]

Throws: Any exception thrown by the selected constructor of T.

This is not exception safety.
@par could be a good generic solution, except that it stands for "paragraph", and I think the current layout (template) adds too much sections. For my private use I changed it to render:

Preconditions: x >= 0.
Returns: _val.
Throws: Nothing.

I need the docs to be concise.
And now the word "paragraph" may not fit.