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

[David Lonie]

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> 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> 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> 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
>> >
>> > 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
>> >
>> > 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
>> >
>> >
>> _______________________________________________
>> 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
>>
>>
>
> _______________________________________________
> 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
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://public.kitware.com/pipermail/vtkusers/attachments/20160919/2e555d47/attachment.html>