[vtkusers] [vtk-developers] poll - vtk doxygen style
Berk Geveci
berk.geveci at kitware.com
Tue Sep 20 15:10:17 EDT 2016
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/ecf3268a/attachment.html>
More information about the vtkusers
mailing list