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, ...)?
I think it comes down to preference and readability.
For example I like to use the following:
/*----------------------
| Function
| Author:
| Dependencies:
----------------------*/
/*----------------------
| Section
-----------------------*/
//Comments in sections
I use this in conjunction with the following rules for readability.
The easiest way I have found to block quote is to highlight the code and then to use the keyboard short-cut Ctrl + Shift + / to comment out that block. Works in most editors.
Hope that helps.