[vtkusers] [vtk-developers] poll - vtk doxygen style
David E DeMarle
dave.demarle at kitware.com
Tue Sep 20 16:07:37 EDT 2016
Sounds like a plan.
I'll address Berk's and Dan's suggestions then hand off to you.
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 4:00 PM, David Gobbi <david.gobbi at gmail.com> wrote:
> Dave,
>
> Probably the easiest thing is if you tell me when you're ready to merge
> the doxygen change, and then I'll use that as a base for the brace change
> MR (i.e. I'll re-run my script). Then when the regenerated brace-change MR
> is merged into VTK, the doxygen change will go with it.
>
> We obviously cannot merge the brace-change MR into the doxyen MR or vice
> versa... there would be thousands of conflicts. These kind of changes have
> to be serial.
>
> - David
>
> On Tue, Sep 20, 2016 at 1:27 PM, David E DeMarle <dave.demarle at kitware.com
> > wrote:
>
>> Had been planing on this one day and then the indents the next, but sure
>> we can merge this into that branch first or the other way around.
>>
>> Then we'll all just have a single merge commit to jump over rather than
>> two.
>>
>> I can take a stab at the groups with a better condition here: 547
>> <https://gitlab.kitware.com/vtk/vtk/blob/6f6b5333c8dde9b8df9dfb8d9d5bbf0500975f22/Utilities/Doxygen/doc_header2doxygen.pl#L547>
>>
>>
>> <https://gitlab.kitware.com/vtk/vtk/blob/6f6b5333c8dde9b8df9dfb8d9d5bbf0500975f22/Utilities/Doxygen/doc_header2doxygen.pl#L547>
>>
>>
>>
>> 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 3:10 PM, Berk Geveci <berk.geveci at kitware.com>
>> wrote:
>>
>>> That seems to generate a lot of unnecessary group ( //@{ ) markings.
>>> Isn't there a way of avoiding that? Also, I thought that this was going to
>>> be merged together with the indentation changes to avoid multiple conflicts?
>>>
>>> On Tue, Sep 20, 2016 at 2:20 PM, David E DeMarle <
>>> dave.demarle at kitware.com> wrote:
>>>
>>>> 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
>>>>>>
>>>>>
>>>>>
>>>>
>>>> _______________________________________________
>>>> Powered by www.kitware.com
>>>>
>>>> Visit other Kitware open-source projects at
>>>> http://www.kitware.com/opensource/opensource.html
>>>>
>>>> Search the list archives at: http://markmail.org/search/?q=
>>>> vtk-developers
>>>>
>>>> Follow this link to subscribe/unsubscribe:
>>>> http://public.kitware.com/mailman/listinfo/vtk-developers
>>>>
>>>>
>>>>
>>>
>>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://public.kitware.com/pipermail/vtkusers/attachments/20160920/6b296d83/attachment-0001.html>
More information about the vtkusers
mailing list