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

[David Cole]

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