1

I have some doubts about the style of C code comments. like this:

/* \brief Creates a new shm pcm */

sometimes it like this:

/* \!brief Creates a new shm PCM */

What is the difference between the "\brief" and "\!brief"

Sander De Dycker
  • 16,053
  • 1
  • 35
  • 40
375
  • 57
  • 6
  • 2
    For the compiler? None whatsoever. It simply replaces all comments with a single space, which is then ignored. Contents of comments are often used by other tools, like documentation generators. You need to figure out which documentation generator is used by ALSA and check its documentation. – Some programmer dude Oct 22 '19 at 06:31
  • 3
    That should be [doxygen](http://www.doxygen.nl/) (ie. [`\brief`](http://www.doxygen.nl/manual/commands.html#cmdbrief)). But are you sure you actually saw `\!brief` used ? Because that is probably an error. – Sander De Dycker Oct 22 '19 at 06:55
  • in alsa-lib-1.1.15， this style of comment is very common. – 375 Oct 22 '19 at 08:36
  • also-lib 1.1.15 ? I see that the newest version is 1.1.9. Where can one get the source code showing this kind of comments as I found in the alsa-lib-1.1.9.tar.bz2 just in the files pcm.c and pcm-hw.construct ? I think here it is definitely a mistake and should be `\brief` also seen what I see in the documentation of `snd_pcm_query_chmaps` (https://www.alsa-project.org/alsa-doc/alsa-lib/group___p_c_m.html#ga675cb6a0fd5470345105574216a652c2) (marcolz thanks for the link to the documentation) – albert Oct 22 '19 at 08:51
  • sorry, my mistake. it's alsa-lib-1.1.5.this style will make the characters red in vscode. I use this style to make the information more eye-catching. – 375 Oct 22 '19 at 08:54
  • 1
    My guess is that all instances of `\!brief` are caused by a typo that was then copy-pasted a few times. Ref. [commit](https://github.com/alsa-project/alsa-lib/commit/3c4a22ea49a881cdbfe2d50eef94b17e38104734) and [commit](https://github.com/alsa-project/alsa-lib/commit/63f6f4a6103e55d242440488999e648beb5e4e4d). The fact that it shows up as red in your IDE is probably a sign that your IDE recognized the error, and wants to draw your attention to it. – Sander De Dycker Oct 22 '19 at 09:14
  • I fully agree with @SanderDeDycker – albert Oct 22 '19 at 09:20
  • Thanks you all. It's my fist time to this style. Maybe it's a typo. also thanks @marcolz for the link. – 375 Oct 22 '19 at 09:30

1 Answers1

7

Those are comments meant for DoxyGen, a system to generate documentation from the source code.

For the compiler, there is absolutely no difference at all.

DoxyGen expects /*! */ and /** */ to flag that the comments are meant for it, see the documentation.

As albert mentioned, it looks like that in src/pcm/pcm.c some years back someone confused /*! \brief ... with /* \!brief

marcolz
  • 2,880
  • 2
  • 23
  • 28
  • The comment `\brief` is a doxygen commands but are used in other documentation packages as well. The `\!brief`is not a doxygen command. Furthermore the entire comment is skipped by doxygen as well as the comment starts with `/*` and this is a regular C / Cpp starting commaent and not a doxygen starting comment this should be `/**` etc.. – albert Oct 22 '19 at 07:45
  • True, but ALSA lib uses DoxyGen, see https://www.alsa-project.org/alsa-doc/alsa-lib/ although the mentioning of ALSA was removed from the question in the mean time... – marcolz Oct 22 '19 at 08:23
  • I think your comment on the question is correct and there was confusion with `/*! */` – marcolz Oct 22 '19 at 08:25
  • thanks, i learn that /** is a Javadoc style, /*! is a Qt style. but i still confuse with \!brief, this style will make the characters red in vscode. – 375 Oct 22 '19 at 08:52