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

[Marcus D. Hanwell]

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
>
>