Skip to content

Name the parameters isInList actually takes - #58

Open
karpovantonme wants to merge 1 commit into
prashjha:mainfrom
karpovantonme:docs-isinlist-params
Open

Name the parameters isInList actually takes#58
karpovantonme wants to merge 1 commit into
prashjha:mainfrom
karpovantonme:docs-isinlist-params

Conversation

@karpovantonme

Copy link
Copy Markdown

Fixes #

Proposed Changes

  • isInList documents tag and tags, but those are the parameters of isTagInList right below it -- the block looks copied from there. The function itself takes i and list, so Doxygen drops both entries and it renders with no parameters at all
  • comments only, no code touched
$ clang++ -Wdocumentation -fsyntax-only -Isrc t.cpp
src/util/methods.h:260:11: warning: parameter 'tag' not found in the function declaration
src/util/methods.h:261:11: warning: parameter 'tags' not found in the function declaration

Two warnings before, none after.

Any background context you want to provide?

The wording is not invented, addToList two functions further down already documents the same pair:

/*!
 * @brief Add element to the list
 * @param i Item to add
 * @param list Vector of elements
 */
template <typename T>
inline void addToList(const T &i, std::vector<T> &list) {

Found while running -Wdocumentation across a set of C++ projects. It was the only hit in PeriDEM that is a real mismatch -- the rest of the header uses @return name description, which Doxygen handles fine and I left alone

The block documents tag and tags, which belong to isTagInList just below
it. isInList takes i and list, so Doxygen drops both entries and the
function renders with no parameters at all.

clang -Wdocumentation on util/methods.h: two warnings before, none after.
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