Skip to content

Fix @param names in synchronized_value - #420

Open
karpovantonme wants to merge 1 commit into
boostorg:developfrom
karpovantonme:docs/synchronized-value-params
Open

Fix @param names in synchronized_value#420
karpovantonme wants to merge 1 commit into
boostorg:developfrom
karpovantonme:docs/synchronized-value-params

Conversation

@karpovantonme

Copy link
Copy Markdown

Thirteen @param tags in synchronized_value.hpp that do not match the parameters below them. Documentation only, no code touched.

The first parameter is called val, the comments say value

/**
 * @param value constant reference of the value to protect.
 * @param mtx reference to the mutex used to protect the value.
 */
const_strict_lock_ptr(T const& val, Lockable & mtx) :

Same in strict_lock_ptr, const_unique_lock_ptr and unique_lock_ptr.

Worth noting because it makes the fix less obvious than it looks: the name is not consistent in the file itself. unique_lock_ptr takes value in its three tag constructors and val in the plain one, so the comments are already correct in some places and wrong in others. I changed only the ones where the code says val and left the rest alone.

The other way round would work too: rename the parameters to value everywhere and leave every comment as it is. That touches declarations rather than comments, so I did not want to decide it on your behalf. Say the word and I will send that version instead.

@param tag on an unnamed parameter

/**
 * @param tag of type adopt_lock_t used to differentiate the constructor.
 */
unique_lock_ptr(T & value, Lockable & mtx, adopt_lock_t) BOOST_NOEXCEPT

The third argument has no name, and Doxygen cannot attach a @param to one. Naming it would go against the rest of the file, where every tag argument is unnamed, so those six lines became @note and say the same thing.

Both kinds are what clang -Wdocumentation reports as parameter '...' not found in the function declaration.

Two things in one file.

The lock pointer constructors spell the first parameter val, while every
comment above them says value. The name is not consistent in the file
itself: unique_lock_ptr takes value in the three tag constructors and val
in the plain one, so the comments happen to be right in half the cases and
wrong in the other half. Comments now follow the code in each place.

The third argument of the tag constructors has no name, and Doxygen cannot
attach a @param to an unnamed parameter. Naming it would go against the
style of the file, so those lines became @note instead.
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.

1 participant