[Ctk-developers] ctk documentation

[Steve Pieper]

Hi Guys -

In general I vote for following the coding/documenting style of the 
superclass - so QWidgets should follow Qt style, vtkObjects should 
follow VTK style, etc...  That way code can most easily be merged back 
to the upstream projects if/when that becomes desirable.

-Steve

On 11/10/2010 09:30 AM, Julien Finet wrote:
> Hi Dean,
>
> There are different styles of comments currently in CTK. However they
> seem to be closely following the Qt documentation style. The style is
> very similar to the standard Doxygen style:
>
> /*!
>      \class QPushButton
>      \brief The QPushButton widget provides a command button.
>
>      \ingroup basicwidgets
>
>
>      The push button, or command button, is perhaps the most commonly
>      used widget in any graphical user interface. Push (click) a button
>      to command the computer to perform some action, or to answer a
>      question. Typical buttons are OK, Apply, Cancel, Close, Yes, No
>      and Help.
>      ...
>      \sa QToolButton
> */
>
> Sometimes (in Libs/Widgets), we use /// in front of each line of comment
> instead of wrapping all the comments with /*!  */
> I've seen /** */ as well.
>
> As you suggested, we should probably pick a style and stick with it.
> I have a preference for following the Qt style (but adding the comments
> in the .h file and not in the .cpp). If we end up all having a very
> different opinion we can start a doodle poll.
>
> Julien.
>
> On Wed, Nov 10, 2010 at 8:39 AM, Dean Inglis <dean.inglis at camris.ca
> <mailto:dean.inglis at camris.ca>> wrote:
>
>     Is there a plan to add documentation about ctk classes
>     and their methods in a manner similar to what is done
>     with vtk or itk classes?  ie. vtk style is ...
>
>     // .NAME ctkClass - brief description of what it does
>     // .SECTION Description
>     // The longer description of what it does etc.
>
>     // .SECTION Event Bindings
>     // something about the slots and signals?
>
>     // .SECTION Caveats
>     // useage warnings
>
>     // .SECTION See Also
>     // other classes related to or critical to this class
>
>     Dean
>     _______________________________________________
>     Ctk-developers mailing list
>     Ctk-developers at commontk.org <mailto:Ctk-developers at commontk.org>
>     http://public.kitware.com/cgi-bin/mailman/listinfo/ctk-developers
>
>
>
>
> _______________________________________________
> Ctk-developers mailing list
> Ctk-developers at commontk.org
> http://public.kitware.com/cgi-bin/mailman/listinfo/ctk-developers