<div dir="ltr"><div><div>@Berk and @David<br></div><br>I made a small change to the script that improves things substantially.<br></div>I can think of cases where it still puts single items inside a group, but we can take those out manually after the fact.<br><br><div><div><div><br></div></div></div></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 4:33 PM, David Gobbi <span dir="ltr"><<a href="mailto:david.gobbi@gmail.com" target="_blank">david.gobbi@gmail.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">Regarding the group markings, be careful when removing them, because removing them will cause doxygen to change the order in which the methods are displayed (I seem to recall that ungrouped methods are either all displayed at the top or all displayed at the bottom or somesuch). I might even recommend that you leave them all in.</div><div class="HOEnZb"><div class="h5"><div class="gmail_extra"><br><div class="gmail_quote">On Tue, Sep 20, 2016 at 2:07 PM, 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>Sounds like a plan.<br></div><br>I'll address Berk's and Dan's suggestions then hand off to you.<br><br><br></div><div class="gmail_extra"><span><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><div class="gmail_quote">On Tue, Sep 20, 2016 at 4:00 PM, David Gobbi <span dir="ltr"><<a href="mailto:david.gobbi@gmail.com" target="_blank">david.gobbi@gmail.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">Dave,<div><br></div><div>Probably the easiest thing is if you tell me when you're ready to merge the doxygen change, and then I'll use that as a base for the brace change MR (i.e. I'll re-run my script). Then when the regenerated brace-change MR is merged into VTK, the doxygen change will go with it.</div><div><br></div><div>We obviously cannot merge the brace-change MR into the doxyen MR or vice versa... there would be thousands of conflicts. These kind of changes have to be serial.</div><span><font color="#888888"><div><br></div><div> - David</div></font></span></div><div><div><div class="gmail_extra"><br><div class="gmail_quote">On Tue, Sep 20, 2016 at 1:27 PM, 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>Had been planing on this one day and then the indents the next, but sure we can merge this into that branch first or the other way around.</div><div><br></div><div>Then we'll all just have a single merge commit to jump over rather than two.</div><div><br></div><div>I can take a stab at the groups with a better condition here: <a href="https://gitlab.kitware.com/vtk/vtk/blob/6f6b5333c8dde9b8df9dfb8d9d5bbf0500975f22/Utilities/Doxygen/doc_header2doxygen.pl#L547" target="_blank">547</a></div><a href="https://gitlab.kitware.com/vtk/vtk/blob/6f6b5333c8dde9b8df9dfb8d9d5bbf0500975f22/Utilities/Doxygen/doc_header2doxygen.pl#L547" target="_blank"><br></a><div><br></div><div><br></div></div><div class="gmail_extra"><span><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><div class="gmail_quote">On Tue, Sep 20, 2016 at 3:10 PM, Berk Geveci <span dir="ltr"><<a href="mailto:berk.geveci@kitware.com" target="_blank">berk.geveci@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">That seems to generate a lot of unnecessary group ( //@{ ) markings. Isn't there a way of avoiding that? Also, I thought that this was going to be merged together with the indentation changes to avoid multiple conflicts?</div><div><div><div class="gmail_extra"><br><div class="gmail_quote">On Tue, Sep 20, 2016 at 2:20 PM, 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><a href="https://gitlab.kitware.com/vtk/vtk/merge_requests/1932" target="_blank">https://gitlab.kitware.com/vtk<wbr>/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"><span><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><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/vtk<wbr>/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/vtk<wbr>/vtk/merge_requests/1911</a><br></div>That will go in very soon too.<br><br></div><div class="gmail_extra"><span><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><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></div></div>
<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>
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>
<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>
<br>
<br></blockquote></div><br></div>
</div></div></blockquote></div><br></div></div></div>
</blockquote></div><br></div>
</div></div></blockquote></div><br></div></div></div>
</blockquote></div><br></div>
</div></div></blockquote></div><br></div>