[vtk-developers] [vtkusers] poll - vtk doxygen style

[Andrew Maclean]

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.

Personally I would favour style B without the asterisks in front of every
line i.e the one I use for the class description.
The reasons for this are:
 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.
 2. It looks clean and is easy to read.

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.


A:
      //! Test for a leap year.
      /*!
        * @param year Year
        * @param calendar The calendar to use.
        * @return true if it is a leap year.
        */

or B:

      /**
      * Calculate the Julian day number of the date.
      * The Proleptic Gregorian Calendar is used.
      *
      * Not valid for ymd < -4713 12 25.

      * @param ymd The year, month and day.
      *
      * @return The Julian day number of the date, an integer
      *  running from noon to noon.
      */

For a class description I use this, style B with no asterisks in front of
every line:
  /**
    This class provides conversion routines between Calendrical dates and
     times and the date and time as a Julian Day Number (JDN) and fraction
     of the day (FoD).

    The Julian Day is defined as the interval of time in days and fractions
of
     a day since 4713 B.C. January 1, Greenwich noon Julian proleptic
calendar.
    ... more stuff ...
    */

See: https://gitlab.com/amaclean/date-time in this, there are C++, Python
and Java implementations of the same code.

Regards
   Andrew
-- 
___________________________________________
Andrew J. P. Maclean

___________________________________________
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://public.kitware.com/pipermail/vtk-developers/attachments/20160918/06fa8765/attachment.html>