[vtkusers] [vtk-developers] poll - vtk doxygen style
David Gobbi
david.gobbi at gmail.com
Tue Sep 20 16:33:33 EDT 2016
Regarding the group markings, be careful when removing them, because
removing them will cause doxygen to change the order in which the methods
are displayed (I seem to recall that ungrouped methods are either all
displayed at the top or all displayed at the bottom or somesuch). I might
even recommend that you leave them all in.
On Tue, Sep 20, 2016 at 2:07 PM, David E DeMarle <dave.demarle at kitware.com>
wrote:
> 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/mail
>>>>>>>> man/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_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
>>>>>>>>
>>>>>>>> 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/c353f785/attachment.html>
More information about the vtkusers
mailing list