title: Comments section and comment blocks in C
body: <p>Accordingly to <a href="http://www.doxygen.nl/manual/docblocks.html" rel="nofollow noreferrer">Doxygen's manual</a>, 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).</p>
  
  <p>If I agree that the most common header for a function is:</p>
  
  <pre><code>/** 
   * Brief description.
   *
   * @param a first parameter
   * @return if any return value
   * 
   * Detailed description
   **/
  </code></pre>
  
  <p>Unfortunately this solution is quite tiresome when I need to quickly comment a block of code with <code>/*</code> ... <code>*/</code>. It is the reason why I prefer using <code>//</code> which doesn't interact with <code>/*..*/</code>. 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.</p>
  
  <p>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: </p>
  
  <pre><code>/**
   * @file foo.c
   *
   * StackOverflow Example
   **/
  
  /*************************************************************
   * Includes
   ************************************************************/
  #include &lt;stdio.h&gt;
  ...
  
  /*************************************************************
   * Prototypes
   ************************************************************/
  void foo();
  void bar();
  ...
  </code></pre>
  
  <p>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, ...)?</p>