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

[Dan Lipsa]

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