<div dir="ltr"><div><div><a href="https://gitlab.kitware.com/vtk/vtk/merge_requests/1932">https://gitlab.kitware.com/vtk/vtk/merge_requests/1932</a><br><br></div>Pending test failures I'll merge Wednesday or Thursday evening.<br></div><br></div><div class="gmail_extra"><br clear="all"><div><div class="gmail_signature" data-smartmail="gmail_signature">David E DeMarle<br>Kitware, Inc.<br>R&D Engineer<br>21 Corporate Drive<br>Clifton Park, NY 12065-8662<br>Phone: 518-881-4909</div></div>
<br><div class="gmail_quote">On Tue, Sep 20, 2016 at 8:45 AM, David E DeMarle <span dir="ltr"><<a href="mailto:dave.demarle@kitware.com" target="_blank">dave.demarle@kitware.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div dir="ltr"><div><div><div><div><div><div>I count 9 votes for /** to 5 (including my own) for /// and none for /*! or //!.<br><br></div>I'll go with this then:<br></div>/**<br> something<br></div> blah blah blah<br>*/<br><br></div>I'll revise <a href="https://gitlab.kitware.com/vtk/vtk/merge_requests/1932" target="_blank">https://gitlab.kitware.com/<wbr>vtk/vtk/merge_requests/1932</a> and on Thursday.<br></div><br>Note<br><br>David Gobbi has another big style change coming that is going to modernizing our indentation style in implementation files.<br>See: <a href="https://gitlab.kitware.com/vtk/vtk/merge_requests/1911" target="_blank">https://gitlab.kitware.com/<wbr>vtk/vtk/merge_requests/1911</a><br></div>That will go in very soon too.<br><br></div><div class="gmail_extra"><span class=""><br clear="all"><div><div data-smartmail="gmail_signature">David E DeMarle<br>Kitware, Inc.<br>R&D Engineer<br>21 Corporate Drive<br>Clifton Park, NY 12065-8662<br>Phone: <a href="tel:518-881-4909" value="+15188814909" target="_blank">518-881-4909</a></div></div>
<br></span><div><div class="h5"><div class="gmail_quote">On Mon, Sep 19, 2016 at 3:27 PM, Michael Jackson <span dir="ltr"><<a href="mailto:mike.jackson@bluequartz.net" target="_blank">mike.jackson@bluequartz.net</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">+1 for ><span><br>
> /**<br>
> * Document code<br>
> * @param<br>
> */<br>
<br></span>
and leave them in the header file<br>
<br>
-- <br>
Michael A. Jackson<br>
BlueQuartz Software, LLC<br>
[e]: <a href="mailto:mike.jackson@bluequartz.net" target="_blank">mike.jackson@bluequartz.net</a><br>
<br>
<br>
David Lonie wrote:<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><span>
One more vote for /** ... */ with leading * on lines in-between, and<br>
keeping the docs in the headers. Jumping to a header is much faster and<br>
easier than opening a doxygen page with modern IDEs. Plus, I doubt<br>
anyone would want to volunteer for the task of moving all the<br>
docstrings, and it doesn't sound easy to script/automate.<br>
<br>
On Mon, Sep 19, 2016 at 9:40 AM, Dan Lipsa <<a href="mailto:dan.lipsa@kitware.com" target="_blank">dan.lipsa@kitware.com</a><br></span><span>
<mailto:<a href="mailto:dan.lipsa@kitware.com" target="_blank">dan.lipsa@kitware.com</a>><wbr>> wrote:<br>
<br>
I also prefer this doxygen style:<br>
<br>
/**<br>
* Document code<br>
* @param<br>
*/<br>
<br>
as it creates a nice header for a function that contains the<br>
documentation.<br>
<br>
I think documentation should stay in the header as it is part of the<br>
interface of the module.<br>
<br>
<br>
<br>
<br>
On Mon, Sep 19, 2016 at 8:56 AM, Marcus D. Hanwell<br></span><span>
<<a href="mailto:marcus.hanwell@kitware.com" target="_blank">marcus.hanwell@kitware.com</a> <mailto:<a href="mailto:marcus.hanwell@kitware.com" target="_blank">marcus.hanwell@kitware<wbr>.com</a>>> wrote:<br>
<br>
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<br>
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<br>
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<br>
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 //!<br>
but I<br>
am sure I could adapt were that chosen.<br>
<br>
On Sat, Sep 17, 2016 at 10:37 PM, David Cole via vtk-developers<br></span><span>
<<a href="mailto:vtk-developers@vtk.org" target="_blank">vtk-developers@vtk.org</a> <mailto:<a href="mailto:vtk-developers@vtk.org" target="_blank">vtk-developers@vtk.org</a><wbr>>> wrote:<br>
> Another argument for keeping all documentation in the header<br>
files is so<br>
> it's available in an install-tree-only situation. Some people<br>
use VTK<br>
> without the source tree around, and having the docs built<br>
into the header<br>
> files is quite nice in that scenario. If it were in the cxx<br>
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<br></span>
<<a href="mailto:david.thompson@kitware.com" target="_blank">david.thompson@kitware.com</a> <mailto:<a href="mailto:david.thompson@kitware.com" target="_blank">david.thompson@kitware<wbr>.com</a>>><span><br>
> wrote:<br>
><br>
> Hi Andrew,<br>
><br>
> ...<br>
><br>
> For what it is worth, I also believe that documentation<br>
should be with the<br>
> declaration simply because the header files are the ones<br>
people tend to<br>
> first look at not the definition. This is what VTK currently<br>
does. ...<br>
><br>
><br>
> I think that moving method (not class) documentation out of<br>
the headers<br>
> makes the headers much more terse and legible. For the vast<br>
majority of<br>
> classes, the method names themselves are enough<br>
documentation. In cases<br>
> where method names are not enough, it is nice to have the<br>
implementation<br>
> nearby. Methods with inline or macro-generated<br>
implementations would still<br>
> have documentation in the header, as would enums.<br>
><br>
> David<br>
><br>
> ______________________________<wbr>_________________<br></span>
> Powered by <a href="http://www.kitware.com" rel="noreferrer" target="_blank">www.kitware.com</a> <<a href="http://www.kitware.com" rel="noreferrer" target="_blank">http://www.kitware.com</a>><span><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/opensou<wbr>rce/opensource.html</a><br>
<<a href="http://www.kitware.com/opensource/opensource.html" rel="noreferrer" target="_blank">http://www.kitware.com/openso<wbr>urce/opensource.html</a>><br>
><br>
> Please keep messages on-topic and check the VTK FAQ at:<br></span>
> <a href="http://www.vtk.org/Wiki/VTK_FAQ" rel="noreferrer" target="_blank">http://www.vtk.org/Wiki/VTK_FA<wbr>Q</a> <<a href="http://www.vtk.org/Wiki/VTK_FAQ" rel="noreferrer" target="_blank">http://www.vtk.org/Wiki/VTK_F<wbr>AQ</a>><span><br>
><br>
> Search the list archives at:<br>
<a href="http://markmail.org/search/?q=vtkusers" rel="noreferrer" target="_blank">http://markmail.org/search/?q=<wbr>vtkusers</a><br>
<<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/mail<wbr>man/listinfo/vtkusers</a><br>
<<a href="http://public.kitware.com/mailman/listinfo/vtkusers" rel="noreferrer" target="_blank">http://public.kitware.com/mai<wbr>lman/listinfo/vtkusers</a>><br>
><br>
><br>
> ______________________________<wbr>_________________<br></span>
> Powered by <a href="http://www.kitware.com" rel="noreferrer" target="_blank">www.kitware.com</a> <<a href="http://www.kitware.com" rel="noreferrer" target="_blank">http://www.kitware.com</a>><span><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/opensou<wbr>rce/opensource.html</a><br></span><span>
<<a href="http://www.kitware.com/opensource/opensource.html" rel="noreferrer" target="_blank">http://www.kitware.com/openso<wbr>urce/opensource.html</a>><br>
><br>
> Search the list archives at:<br>
<a href="http://markmail.org/search/?q=vtk-developers" rel="noreferrer" target="_blank">http://markmail.org/search/?q=<wbr>vtk-developers</a><br>
<<a href="http://markmail.org/search/?q=vtk-developers" rel="noreferrer" target="_blank">http://markmail.org/search/?q<wbr>=vtk-developers</a>><br>
><br>
> Follow this link to subscribe/unsubscribe:<br>
> <a href="http://public.kitware.com/mailman/listinfo/vtk-developers" rel="noreferrer" target="_blank">http://public.kitware.com/mail<wbr>man/listinfo/vtk-developers</a><br>
<<a href="http://public.kitware.com/mailman/listinfo/vtk-developers" rel="noreferrer" target="_blank">http://public.kitware.com/mai<wbr>lman/listinfo/vtk-developers</a>><br>
><br>
><br>
______________________________<wbr>_________________<br></span>
Powered by <a href="http://www.kitware.com" rel="noreferrer" target="_blank">www.kitware.com</a> <<a href="http://www.kitware.com" rel="noreferrer" target="_blank">http://www.kitware.com</a>><span><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/opensou<wbr>rce/opensource.html</a><br></span><span>
<<a href="http://www.kitware.com/opensource/opensource.html" rel="noreferrer" target="_blank">http://www.kitware.com/openso<wbr>urce/opensource.html</a>><br>
<br>
Search the list archives at:<br>
<a href="http://markmail.org/search/?q=vtk-developers" rel="noreferrer" target="_blank">http://markmail.org/search/?q=<wbr>vtk-developers</a><br>
<<a href="http://markmail.org/search/?q=vtk-developers" rel="noreferrer" target="_blank">http://markmail.org/search/?q<wbr>=vtk-developers</a>><br>
<br>
Follow this link to subscribe/unsubscribe:<br>
<a href="http://public.kitware.com/mailman/listinfo/vtk-developers" rel="noreferrer" target="_blank">http://public.kitware.com/mail<wbr>man/listinfo/vtk-developers</a><br>
<<a href="http://public.kitware.com/mailman/listinfo/vtk-developers" rel="noreferrer" target="_blank">http://public.kitware.com/mai<wbr>lman/listinfo/vtk-developers</a>><br>
<br>
<br>
<br>
______________________________<wbr>_________________<br></span>
Powered by <a href="http://www.kitware.com" rel="noreferrer" target="_blank">www.kitware.com</a> <<a href="http://www.kitware.com" rel="noreferrer" target="_blank">http://www.kitware.com</a>><span><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/opensou<wbr>rce/opensource.html</a><br>
<<a href="http://www.kitware.com/opensource/opensource.html" rel="noreferrer" target="_blank">http://www.kitware.com/openso<wbr>urce/opensource.html</a>><br>
<br>
Please keep messages on-topic and check the VTK FAQ at:<br></span>
<a href="http://www.vtk.org/Wiki/VTK_FAQ" rel="noreferrer" target="_blank">http://www.vtk.org/Wiki/VTK_FA<wbr>Q</a> <<a href="http://www.vtk.org/Wiki/VTK_FAQ" rel="noreferrer" target="_blank">http://www.vtk.org/Wiki/VTK_F<wbr>AQ</a>><span><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>
<<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/mail<wbr>man/listinfo/vtkusers</a><br>
<<a href="http://public.kitware.com/mailman/listinfo/vtkusers" rel="noreferrer" target="_blank">http://public.kitware.com/mai<wbr>lman/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 <a href="http://www.kitware.com/opensource/opensource.html" rel="noreferrer" target="_blank">http://www.kitware.com/opensou<wbr>rce/opensource.html</a><br>
<br>
Please keep messages on-topic and check the VTK FAQ at: <a href="http://www.vtk.org/Wiki/VTK_FAQ" rel="noreferrer" target="_blank">http://www.vtk.org/Wiki/VTK_FA<wbr>Q</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/mail<wbr>man/listinfo/vtkusers</a><br>
</span></blockquote><div><div>
______________________________<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/opensou<wbr>rce/opensource.html</a><br>
<br>
Please keep messages on-topic and check the VTK FAQ at: <a href="http://www.vtk.org/Wiki/VTK_FAQ" rel="noreferrer" target="_blank">http://www.vtk.org/Wiki/VTK_FA<wbr>Q</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/mail<wbr>man/listinfo/vtkusers</a><br>
</div></div></blockquote></div><br></div></div></div>
</blockquote></div><br></div>