Skip to content

[doc] Drop the dangling \param from empty_formatter - #133

Open
karpovantonme wants to merge 1 commit into
boostorg:developfrom
karpovantonme:doc/empty-formatter-param
Open

[doc] Drop the dangling \param from empty_formatter#133
karpovantonme wants to merge 1 commit into
boostorg:developfrom
karpovantonme:doc/empty-formatter-param

Conversation

@karpovantonme

Copy link
Copy Markdown
Contributor

empty_formatter takes its argument only to deduce a type, so the argument has no name:

    \param - container used to select a correct value_type for the
                 resulting empty_container<>.
    ...
    empty_formatter(const RangeT&)

Doxygen has nothing to bind that \param to, so the description does not reach the generated page. The dash standing in for the name is not a name either. It is also the only one of its kind: 1 of 725 \param tags in this library, and I did not find another in the 44 other Boost libraries I have checked out

So the explanation moves into the description text, where it is not tied to a name, and the argument gets a commented name the way string/detail/replace_storage.hpp:65 already writes it:

    empty_formatter(const RangeT& /*Input*/)

And no behaviour change, and no unused-parameter warning added for anyone building with -Wextra

So two siblings in the same header, const_formatter(const RangeT& Format) and dissect_formatter(const FinderT& Finder), both name their argument and both document it correctly, so this was the odd one out

Found with a checker I wrote with help from Claude Opus 5, and read by hand before proposing

The argument of empty_formatter has no name, so \param has nothing to bind
to and Doxygen drops the description. The dash currently standing in for the
name is not a name either, and it is the only one in the library: 1 of 725
\param tags here, and none in the other Boost libraries.

The explanation moves into the description, and the argument gets a commented
name the way replace_storage.hpp already writes it.
@nigels-com

Copy link
Copy Markdown
Contributor

Looks good.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants