Why does a C comment like /* */ need '<'?

Question

My teams C-code guidelines write that it'd be better to place a '<' in a comment like shown below:

#define MAX_PACK_ITEM_NUM 50  /**<  max number of item */

I wonder, what is the real use of this '<' ?

Erm, as an arrow? It's a comment, so there's no one here that's going to be able to answer that. — Brian Roach, Sep 07 '11 at 06:13
Why do people want to close this? It's a perfectly valid question! — Michael Foukarakis, Sep 07 '11 at 06:17
@Michael It is not. It is either too localized or not constructive. Why there is a need for `<` he should ask the creator of the code guidelines in his company. — BЈовић, Sep 07 '11 at 06:43
I'm sure few people learned something from this question, and as for whether it can be considered localized, meta has a pretty good answer: http://meta.stackexchange.com/questions/4818/what-questions-should-be-closed-with-reason-too-localized — Michael Foukarakis, Sep 07 '11 at 07:24
@VJo: If it were a company-specific convention I'd agree, but as it turns out it's about doxygen -- and there are currently 413 questions tagged `[doxygen]`. — Keith Thompson, Sep 07 '11 at 08:08
Off topic, but do your guidelines also recommend `#define ...` instead of `const int` ...? — Daniel Daranas, Dec 12 '18 at 11:10

score 78 · Accepted Answer · edited Dec 12 '18 at 11:05

78

It's a way for doxygen to generate documentation for members of a file/struct/union/class/enum. By using that marker, you can put comments after each member, leading to less clutter. You can read more about it here.

edited Dec 12 '18 at 11:05

albert

8,285
3
19
32

answered Sep 07 '11 at 06:17

Michael Foukarakis

39,737
6
87
123

score 50 · Answer 2 · answered Sep 07 '11 at 06:25

As others have replied, this is probably a comment that is meant for doxygen. When parsing comments, doxygen have some special rules:

An ordinary comment starting with /* is ignored by doxygen.
A comment starting with /** is treated as documentation of the next item after the comment in the source code.
A comment starting with /**< is treated as documentation of the item immediately before the comment in the source code.

Documentation is mostly placed above the documented item, e.g. a function. But in some cases such as a #define it makes sense to put the documentation at the end of the line instead and in that case the /**< marker is needed.

score 17 · Answer 3 · edited Dec 12 '18 at 11:06

17

It is a doxygen syntax for commenting members after declaration/definition.

edited Dec 12 '18 at 11:06

albert

8,285
3
19
32

answered Sep 07 '11 at 06:17

Juraj Blaho

13,301
7
50
96

score 11 · Answer 4 · edited Dec 12 '18 at 11:05

11

I assume your team uses some automated documentation tool which looks for /**<; e.g. Doxygen.

edited Dec 12 '18 at 11:05

albert

8,285
3
19
32

answered Sep 07 '11 at 06:17

ThiefMaster

310,957
84
592
636

6

Doxygen for example uses these angle brackets to describe members etc – arne Sep 07 '11 at 06:17

Why does a C comment like /* */ need '<'?

4 Answers4