Accordingly to Doxygen's manual, there are some standards to correctly comment a program written in C. Unfortunately the way of documenting a program doesn't seem to be well standardized (i.e. GNU Coding Standards).
If I agree that the most common header for a function is:
/** * Brief description. * * @param a first parameter * @return if any return value * * Detailed description **/ Unfortunately this solution is quite tiresome when I need to quickly comment a block of code with /* ... */. It is the reason why I prefer using // which doesn't interact with /*..*/. So what is the most advisable way of writing function comment header? Also most of the today's standards are based on a legacy C89 standards.
Second point of my question concerns the section comments. I often have in different sections in my code that I would like to clearly separate. For example:
/** * @file foo.c * * StackOverflow Example **/ /************************************************************* * Includes ************************************************************/ #include <stdio.h> ... /************************************************************* * Prototypes ************************************************************/ void foo(); void bar(); ... Is there any C programming standard largely used that precisely define how to write such separators based on a study (less cumbersome, less tiring for the eyes, most used by the community, ...)?
\sectionand\subsectionwhich can also function as separators. If you find its syntax tiresome, you could set your editor to spit out snippets with a few keystrokes.