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

David E DeMarle dave.demarle at kitware.com
Tue Sep 20 08:45:52 EDT 2016


I count 9 votes for /** to 5 (including my own) for /// and none for /*! or
//!.

I'll go with this then:
/**
     something
     blah blah blah
*/

I'll revise https://gitlab.kitware.com/vtk/vtk/merge_requests/1932 and on
Thursday.

Note

David Gobbi has another big style change coming that is going to
modernizing our indentation style in implementation files.
See: https://gitlab.kitware.com/vtk/vtk/merge_requests/1911
That will go in very soon too.


David E DeMarle
Kitware, Inc.
R&D Engineer
21 Corporate Drive
Clifton Park, NY 12065-8662
Phone: 518-881-4909

On Mon, Sep 19, 2016 at 3:27 PM, Michael Jackson <
mike.jackson at bluequartz.net> wrote:

> +1 for >
> >     /**
> >       * Document code
> >       * @param
> >       */
>
> and leave them in the header file
>
> --
> Michael A. Jackson
> BlueQuartz Software, LLC
> [e]: mike.jackson at bluequartz.net
>
>
> David Lonie wrote:
>
>> One more vote for /** ... */ with leading * on lines in-between, and
>> keeping the docs in the headers. Jumping to a header is much faster and
>> easier than opening a doxygen page with modern IDEs. Plus, I doubt
>> anyone would want to volunteer for the task of moving all the
>> docstrings, and it doesn't sound easy to script/automate.
>>
>> On Mon, Sep 19, 2016 at 9:40 AM, Dan Lipsa <dan.lipsa at kitware.com
>> <mailto:dan.lipsa at kitware.com>> wrote:
>>
>>     I also prefer this doxygen style:
>>
>>     /**
>>       * Document code
>>       * @param
>>       */
>>
>>     as it creates a nice header for a function that contains the
>>     documentation.
>>
>>     I think documentation should stay in the header as it is part of the
>>     interface of the module.
>>
>>
>>
>>
>>     On Mon, Sep 19, 2016 at 8:56 AM, Marcus D. Hanwell
>>     <marcus.hanwell at kitware.com <mailto:marcus.hanwell at kitware.com>>
>> wrote:
>>
>>         The Doxygen isn't always there, when I am hunting issues I often
>> end
>>         up in the header for the class thanks to my IDE, and having the
>>         Doxygen there is often helpful whether the Doxygen is somewhere
>>         on the
>>         machine or not. I really dislike projects that put it in the
>>         implementation, and disagree on the method names being enough. I
>>         hope
>>         we leave it in the headers, and for the purposes of the migration
>> to
>>         real Doxygen I am not sure the tools have the necessary logic to
>>         move
>>         documentation - just transform the style.
>>
>>         I prefer the
>>
>>         /**
>>           * Document code
>>           * @param
>>           */
>>
>>         Style personally, but /// also works, never really liked the //!
>>         but I
>>         am sure I could adapt were that chosen.
>>
>>         On Sat, Sep 17, 2016 at 10:37 PM, David Cole via vtk-developers
>>         <vtk-developers at vtk.org <mailto:vtk-developers at vtk.org>> wrote:
>>          > Another argument for keeping all documentation in the header
>>         files is so
>>          > it's available in an install-tree-only situation. Some people
>>         use VTK
>>          > without the source tree around, and having the docs built
>>         into the header
>>          > files is quite nice in that scenario. If it were in the cxx
>>         files, it
>>          > wouldn't be available to such users.
>>          >
>>          >
>>          > David
>>          >
>>          >
>>          > On Sep 17, 2016, at 6:47 PM, David Thompson
>>         <david.thompson at kitware.com <mailto:david.thompson at kitware.com>>
>>          > wrote:
>>          >
>>          > Hi Andrew,
>>          >
>>          > ...
>>          >
>>          > 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. ...
>>          >
>>          >
>>          > I think that moving method (not class) documentation out of
>>         the headers
>>          > makes the headers much more terse and legible. For the vast
>>         majority of
>>          > classes, the method names themselves are enough
>>         documentation. In cases
>>          > where method names are not enough, it is nice to have the
>>         implementation
>>          > nearby. Methods with inline or macro-generated
>>         implementations would still
>>          > have documentation in the header, as would enums.
>>          >
>>          >     David
>>          >
>>          > _______________________________________________
>>          > Powered by www.kitware.com <http://www.kitware.com>
>>          >
>>          > Visit other Kitware open-source projects at
>>          > http://www.kitware.com/opensource/opensource.html
>>         <http://www.kitware.com/opensource/opensource.html>
>>          >
>>          > Please keep messages on-topic and check the VTK FAQ at:
>>          > http://www.vtk.org/Wiki/VTK_FAQ <http://www.vtk.org/Wiki/VTK_F
>> AQ>
>>          >
>>          > Search the list archives at:
>>         http://markmail.org/search/?q=vtkusers
>>         <http://markmail.org/search/?q=vtkusers>
>>          >
>>          > Follow this link to subscribe/unsubscribe:
>>          > http://public.kitware.com/mailman/listinfo/vtkusers
>>         <http://public.kitware.com/mailman/listinfo/vtkusers>
>>          >
>>          >
>>          > _______________________________________________
>>          > Powered by www.kitware.com <http://www.kitware.com>
>>          >
>>          > Visit other Kitware open-source projects at
>>          > http://www.kitware.com/opensource/opensource.html
>>         <http://www.kitware.com/opensource/opensource.html>
>>          >
>>          > Search the list archives at:
>>         http://markmail.org/search/?q=vtk-developers
>>         <http://markmail.org/search/?q=vtk-developers>
>>         >
>>         >  Follow this link to subscribe/unsubscribe:
>>          > http://public.kitware.com/mailman/listinfo/vtk-developers
>>         <http://public.kitware.com/mailman/listinfo/vtk-developers>
>>         >
>>         >
>>         _______________________________________________
>>         Powered by www.kitware.com <http://www.kitware.com>
>>
>>         Visit other Kitware open-source projects at
>>         http://www.kitware.com/opensource/opensource.html
>>         <http://www.kitware.com/opensource/opensource.html>
>>
>>         Search the list archives at:
>>         http://markmail.org/search/?q=vtk-developers
>>         <http://markmail.org/search/?q=vtk-developers>
>>
>>         Follow this link to subscribe/unsubscribe:
>>         http://public.kitware.com/mailman/listinfo/vtk-developers
>>         <http://public.kitware.com/mailman/listinfo/vtk-developers>
>>
>>
>>
>>     _______________________________________________
>>     Powered by www.kitware.com <http://www.kitware.com>
>>
>>     Visit other Kitware open-source projects at
>>     http://www.kitware.com/opensource/opensource.html
>>     <http://www.kitware.com/opensource/opensource.html>
>>
>>     Please keep messages on-topic and check the VTK FAQ at:
>>     http://www.vtk.org/Wiki/VTK_FAQ <http://www.vtk.org/Wiki/VTK_FAQ>
>>
>>     Search the list archives at: http://markmail.org/search/?q=vtkusers
>>     <http://markmail.org/search/?q=vtkusers>
>>
>>     Follow this link to subscribe/unsubscribe:
>>     http://public.kitware.com/mailman/listinfo/vtkusers
>>     <http://public.kitware.com/mailman/listinfo/vtkusers>
>>
>>
>> _______________________________________________
>> Powered by www.kitware.com
>>
>> Visit other Kitware open-source projects at
>> http://www.kitware.com/opensource/opensource.html
>>
>> Please keep messages on-topic and check the VTK FAQ at:
>> http://www.vtk.org/Wiki/VTK_FAQ
>>
>> Search the list archives at: http://markmail.org/search/?q=vtkusers
>>
>> Follow this link to subscribe/unsubscribe:
>> http://public.kitware.com/mailman/listinfo/vtkusers
>>
> _______________________________________________
> Powered by www.kitware.com
>
> Visit other Kitware open-source projects at http://www.kitware.com/opensou
> rce/opensource.html
>
> Please keep messages on-topic and check the VTK FAQ at:
> http://www.vtk.org/Wiki/VTK_FAQ
>
> Search the list archives at: http://markmail.org/search/?q=vtkusers
>
> Follow this link to subscribe/unsubscribe:
> http://public.kitware.com/mailman/listinfo/vtkusers
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://public.kitware.com/pipermail/vtkusers/attachments/20160920/50be832a/attachment.html>


More information about the vtkusers mailing list