[vtk-developers] [vtkusers] poll - vtk doxygen style
David E DeMarle
dave.demarle at kitware.com
Tue Sep 20 15:27:45 EDT 2016
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/b0eb63e1/attachment-0001.html>
More information about the vtk-developers
mailing list