[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