[vtkusers] [vtk-developers] poll - vtk doxygen style

Berk Geveci berk.geveci at kitware.com
Wed Sep 21 10:32:18 EDT 2016 

Sounds great! Thanks Dave.

On Wed, Sep 21, 2016 at 10:29 AM, David E DeMarle <dave.demarle at kitware.com>
wrote:

> @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/mai
>>>>>>>>>> lman/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/mai
>>>>>>>>>> lman/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/20160921/f20fa23a/attachment-0001.html>

More information about the vtkusers mailing list