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

David E DeMarle dave.demarle at kitware.com
Tue Sep 20 14:20:44 EDT 2016


https://gitlab.kitware.com/vtk/vtk/merge_requests/1932

Pending test failures I'll merge Wednesday or Thursday evening.


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

On Tue, Sep 20, 2016 at 8:45 AM, David E DeMarle <dave.demarle at kitware.com>
wrote:

> 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_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 <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/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
>>
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://public.kitware.com/pipermail/vtkusers/attachments/20160920/8bb668f3/attachment.html>


More information about the vtkusers mailing list