<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 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/<wbr>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"><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 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/<wbr>opensource/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/<wbr>mailman/listinfo/vtk-<wbr>developers</a><br>
<br>
<br></blockquote></div><br></div>