Skip to content

Fix \param tags in mcr_howard and put_property - #546

Open
karpovantonme wants to merge 1 commit into
boostorg:developfrom
karpovantonme:docs/fix-param-tags
Open

Fix \param tags in mcr_howard and put_property#546
karpovantonme wants to merge 1 commit into
boostorg:developfrom
karpovantonme:docs/fix-param-tags

Conversation

@karpovantonme

Copy link
Copy Markdown

Two Doxygen comments where the tags do not line up with the code. Documentation only, no code touched.

mcr_howard, howard_cycle_ratio.hpp

Two separate problems in one comment.

Three \param tags are written mid-line, after the text of the previous parameter:

 * \param vim  Vertex Index Map. Read property Map: V -> [0,
 * num_vertices(g)). \param ewm  edge weight map. Read property map: E
 * -> R \param ew2m  edge weight map. Read property map: E -> R+ \param
 * infty A big enough value ...

Doxygen only recognises a command at the start of a line, so ewm and ew2m are currently read as prose belonging to vim, and the two parameters come out undocumented. Looks like a reflow that ran over the tags at some point.

The other half: infty and cmp are documented, but the constructor does not take them. It takes (g, vim, ewm, ew2m), and grep finds no other mcr_howard( in the file. m_cmp exists as a member and is default-constructed, so the comment may date from a version that took a comparator; infty does not appear anywhere in the file outside this comment.

I removed those two and put each remaining tag on its own line.

put_property, visitors.hpp

 * @param tag Event Filter
...
inline property_put< PropertyMap, EventTag > put_property(
    PropertyMap property_map,
    typename property_traits< PropertyMap >::value_type value, EventTag)

The third argument has no name, and Doxygen cannot attach a @param to an unnamed parameter. Naming it would document the tag but goes against what the rest of the file does (every EventTag argument in visitors.hpp is unnamed), so I moved the explanation into the description instead and left the signature alone.

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

I can split this into two pull requests if you would rather review them separately.

mcr_howard: three \param tags were written mid-line, so Doxygen read them
as prose belonging to the previous parameter rather than as tags. Two more
parameters, infty and cmp, are documented but the constructor does not take
them: it takes (g, vim, ewm, ew2m) and there is no other overload.

put_property: the third argument is an unnamed event filter tag. Doxygen
cannot attach a \param to a parameter that has no name, so the tag is now
a sentence in the description instead.

@jeremy-murphy jeremy-murphy left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you!

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