[vtk-developers] [vtkusers] poll - vtk doxygen style
David E DeMarle
dave.demarle at kitware.com
Tue Sep 20 08:45:52 EDT 2016
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_F
>> AQ>
>> >
>> > 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/opensou
> rce/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
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://public.kitware.com/pipermail/vtk-developers/attachments/20160920/50be832a/attachment-0001.html>
More information about the vtk-developers
mailing list