This is an archive of the discontinued LLVM Phabricator instance.

Document how to comment an actual parameter
ClosedPublic

Authored by probinson on Nov 12 2018, 1:48 PM.

Details

Summary

This came up in a code review, but I had nothing to point to.
It seems reasonably common practice.
Happy to put the words somewhere else, if that seems preferable.

Diff Detail

Event Timeline

probinson created this revision.Nov 12 2018, 1:48 PM
dblaikie accepted this revision.Nov 12 2018, 2:11 PM

Sounds good to me - I'd usually put spaces inside the start/end of the comment (& maybe between the comment & the constant) but that's just me - I'm not fussed about which way it's documented (although - best it's documented whatever way clang-format formats it, so as not to be confusing)

This revision is now accepted and ready to land.Nov 12 2018, 2:11 PM
rnk accepted this revision.Nov 13 2018, 10:03 AM

+1 for writing it as you have it, it's what clang-format does, and so far as I know it's the prevailing style.

LGTM for the actual style change, just a wording nit:

llvm/docs/CodingStandards.rst
308

Minor nit: s/To document/When documenting/ to maintain consistency with the previous bullet points

probinson marked an inline comment as done.Nov 14 2018, 5:40 AM

My experiments with clang-format show that it is aware of this convention. It will change /*Prefix*/nullptr to /*Prefix*/ nullptr (inserting a space) and will also change /*Prefix=*/ nullptr to /*Prefix=*/nullptr (removing the space, if the comment ends with =).

This revision was automatically updated to reflect the committed changes.