[vtkusers] [vtk-developers] poll - vtk doxygen style
David Gobbi
david.gobbi at gmail.com
Tue Sep 20 16:00:09 EDT 2016
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/5495b79b/attachment.html>
More information about the vtkusers
mailing list