<div dir="ltr">I also prefer this doxygen style:<div><br></div><div><div>/**</div><div> * Document code</div><div> * @param</div><div> */</div></div><div><br></div><div>as it creates a nice header for a function that contains the documentation.</div><div><br></div><div>I think documentation should stay in the header as it is part of the interface of the module.</div><div><br></div><div><br></div><div><br></div></div><div class="gmail_extra"><br><div class="gmail_quote">On Mon, Sep 19, 2016 at 8:56 AM, Marcus D. Hanwell <span dir="ltr"><<a href="mailto:marcus.hanwell@kitware.com" target="_blank">marcus.hanwell@kitware.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">The Doxygen isn't always there, when I am hunting issues I often end<br>
up in the header for the class thanks to my IDE, and having the<br>
Doxygen there is often helpful whether the Doxygen is somewhere on the<br>
machine or not. I really dislike projects that put it in the<br>
implementation, and disagree on the method names being enough. I hope<br>
we leave it in the headers, and for the purposes of the migration to<br>
real Doxygen I am not sure the tools have the necessary logic to move<br>
documentation - just transform the style.<br>
<br>
I prefer the<br>
<br>
/**<br>
 * Document code<br>
 * @param<br>
 */<br>
<br>
Style personally, but /// also works, never really liked the //! but I<br>
am sure I could adapt were that chosen.<br>
<div><div class="h5"><br>
On Sat, Sep 17, 2016 at 10:37 PM, David Cole via vtk-developers<br>
<<a href="mailto:vtk-developers@vtk.org">vtk-developers@vtk.org</a>> wrote:<br>
> Another argument for keeping all documentation in the header files is so<br>
> it's available in an install-tree-only situation. Some people use VTK<br>
> without the source tree around, and having the docs built into the header<br>
> files is quite nice in that scenario. If it were in the cxx files, it<br>
> wouldn't be available to such users.<br>
><br>
><br>
> David<br>
><br>
><br>
> On Sep 17, 2016, at 6:47 PM, David Thompson <<a href="mailto:david.thompson@kitware.com">david.thompson@kitware.com</a>><br>
> wrote:<br>
><br>
> Hi Andrew,<br>
><br>
> ...<br>
><br>
> For what it is worth, I also believe that documentation should be with the<br>
> declaration simply because the header files are the ones people tend to<br>
> first look at not the definition. This is what VTK currently does. ...<br>
><br>
><br>
> I think that moving method (not class) documentation out of the headers<br>
> makes the headers much more terse and legible. For the vast majority of<br>
> classes, the method names themselves are enough documentation. In cases<br>
> where method names are not enough, it is nice to have the implementation<br>
> nearby. Methods with inline or macro-generated implementations would still<br>
> have documentation in the header, as would enums.<br>
><br>
>     David<br>
><br>
> ______________________________<wbr>_________________<br>
> Powered by <a href="http://www.kitware.com" rel="noreferrer" target="_blank">www.kitware.com</a><br>
><br>
> Visit other Kitware open-source projects at<br>
> <a href="http://www.kitware.com/opensource/opensource.html" rel="noreferrer" target="_blank">http://www.kitware.com/<wbr>opensource/opensource.html</a><br>
><br>
> Please keep messages on-topic and check the VTK FAQ at:<br>
> <a href="http://www.vtk.org/Wiki/VTK_FAQ" rel="noreferrer" target="_blank">http://www.vtk.org/Wiki/VTK_<wbr>FAQ</a><br>
><br>
> Search the list archives at: <a href="http://markmail.org/search/?q=vtkusers" rel="noreferrer" target="_blank">http://markmail.org/search/?q=<wbr>vtkusers</a><br>
><br>
> Follow this link to subscribe/unsubscribe:<br>
> <a href="http://public.kitware.com/mailman/listinfo/vtkusers" rel="noreferrer" target="_blank">http://public.kitware.com/<wbr>mailman/listinfo/vtkusers</a><br>
><br>
><br>
> ______________________________<wbr>_________________<br>
> Powered by <a href="http://www.kitware.com" rel="noreferrer" target="_blank">www.kitware.com</a><br>
><br>
> Visit other Kitware open-source projects at<br>
> <a href="http://www.kitware.com/opensource/opensource.html" rel="noreferrer" target="_blank">http://www.kitware.com/<wbr>opensource/opensource.html</a><br>
><br>
</div></div>> Search the list archives at: <a href="http://markmail.org/search/?q=vtk-developers" rel="noreferrer" target="_blank">http://markmail.org/search/?q=<wbr>vtk-developers</a><br>
<span class="">><br>
> Follow this link to subscribe/unsubscribe:<br>
</span>> <a href="http://public.kitware.com/mailman/listinfo/vtk-developers" rel="noreferrer" target="_blank">http://public.kitware.com/<wbr>mailman/listinfo/vtk-<wbr>developers</a><br>
<span class="">><br>
><br>
______________________________<wbr>_________________<br>
Powered by <a href="http://www.kitware.com" rel="noreferrer" target="_blank">www.kitware.com</a><br>
<br>
Visit other Kitware open-source projects at <a href="http://www.kitware.com/opensource/opensource.html" rel="noreferrer" target="_blank">http://www.kitware.com/<wbr>opensource/opensource.html</a><br>
<br>
</span>Search the list archives at: <a href="http://markmail.org/search/?q=vtk-developers" rel="noreferrer" target="_blank">http://markmail.org/search/?q=<wbr>vtk-developers</a><br>
<span class=""><br>
Follow this link to subscribe/unsubscribe:<br>
</span><a href="http://public.kitware.com/mailman/listinfo/vtk-developers" rel="noreferrer" target="_blank">http://public.kitware.com/<wbr>mailman/listinfo/vtk-<wbr>developers</a><br>
<br>
</blockquote></div><br></div>