[vtkusers] [vtk-developers] poll - vtk doxygen style
Michael Jackson
mike.jackson at bluequartz.net
Mon Sep 19 15:27:44 EDT 2016
+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
More information about the vtkusers
mailing list