[vtk-developers] [vtkusers] 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/vtk-developers/attachments/20160920/8bb668f3/attachment-0001.html>
More information about the vtk-developers
mailing list