[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