<div dir="ltr"><div><br></div><div>In looking through all my code, I have settled on two styles A, and B (often used interchangeably). See also the variant of style B tha I use for the class description.</div><div><br></div><div>Personally I would favour style B without the asterisks in front of every line i.e the one I use for the class description.</div><div>The reasons for this are:</div><div> 1. When writing cross-platform code, especially Python, it is very easy to convert this style to the one favoured by Sphinx. Java, on the other hand, tends to prefer the leading asterisk.</div><div> 2. It looks clean and is easy to read.</div><div><br></div><div>For what it is worth, I also believe that documentation should be with the declaration simply because the header files are the ones people tend to first look at not the definition. This is what VTK currently does.</div><div><br></div><div><br></div><div>A:</div><div>      //! Test for a leap year.</div><div>      /*!</div><div>        * @param year Year</div><div>        * @param calendar The calendar to use.</div><div>        * @return true if it is a leap year.</div><div>        */</div><div><br></div><div>or B:</div><div><br></div><div><div>      /**</div><div>      * Calculate the Julian day number of the date.</div><div>      * The Proleptic Gregorian Calendar is used.</div><div>      *</div><div>      * Not valid for ymd < -4713 12 25.</div><div><br></div><div>      * @param ymd The year, month and day.</div><div>      *</div><div>      * @return The Julian day number of the date, an integer</div><div>      *  running from noon to noon.</div><div>      */</div></div><div><br></div><div>For a class description I use this, style B with no asterisks in front of every line:</div><div><div>  /**</div><div>    This class provides conversion routines between Calendrical dates and</div><div>     times and the date and time as a Julian Day Number (JDN) and fraction</div><div>     of the day (FoD).</div><div><br></div><div>    The Julian Day is defined as the interval of time in days and fractions of</div><div>     a day since 4713 B.C. January 1, Greenwich noon Julian proleptic calendar.</div><div>    ... more stuff ...</div></div><div>    */</div><div><br></div><div>See: <a href="https://gitlab.com/amaclean/date-time">https://gitlab.com/amaclean/date-time</a> in this, there are C++, Python and Java implementations of the same code.</div><div><br></div><div>Regards</div><div>   Andrew</div>-- <br><div class="gmail_signature">___________________________________________<br>Andrew J. P. Maclean<br><br>___________________________________________</div>
</div>