[vtkusers] [vtk-developers] poll - vtk doxygen style
David E DeMarle
dave.demarle at kitware.com
Wed Sep 21 10:29:23 EDT 2016
@Berk and @David
I made a small change to the script that improves things substantially.
I can think of cases where it still puts single items inside a group, but
we can take those out manually after the fact.
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:33 PM, David Gobbi <david.gobbi at gmail.com> wrote:
> 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/20160921/296cdebf/attachment.html>
More information about the vtkusers
mailing list