C 有没有一种 docblock 语法？ 它在 STM32CubeIDE 中有效吗？

Question

Let's say I have a function declaration:

int32_t get_adc_reading();

I want to get any kind of help without peaking to the header file, so...

/**
 * Gets a reading from ADC.
 * @retval 12-bit reading value.
 */
int32_t get_adc_reading();

The IDE seems to ignore the comment. Is it even valid? Is "@retval" valid? Is it documented somewhere?

I try to Google it, but I get nothing.

Maybe I don't know how to ask. I coded mainly in C# before, I'm learning C now.

In C# it was normal I could put a docblock over any object to get IDE hint about that object. It worked in JavaScript in most editors I used. It worked in Python.

Does something like this even exists for C, and if so - where can I find a documentation for it?

Another weird thing I experience while learning C and using Google:

"It looks like there aren't many great matches for your search"

It's even weirder that I often find what I'm looking for much later and see it matches my query, however for some weird reason Google doesn't find it. Let's say my page contains words "plasma capacitor". It is about plasma capacitor. But it's somehow related to C. Let's say it's a C library. I enter "plasma capacitor" in Google and get the infuriating message. Then I'm looking for something completely different, but a little related, then I click on link there, and BLAM: "plasma capacitor" - it is there, but it's just not returned from search.

Answer 1

Unlike C# there isn't a standard comment documentation format for C++. The most used one is Doxygen .

However most modern IDEs can display info about symbols gathered from comments, even if the comments don't follow a particular format.