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

David E DeMarle dave.demarle at kitware.com
Tue Sep 20 16:07:37 EDT 2016


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/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/vtk-developers/attachments/20160920/6b296d83/attachment-0001.html>


More information about the vtk-developers mailing list