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

[David Thompson]

I like the /** ... */ style comments with an explicit \brief keyword where warranted.

I also strongly advocate putting documentation wherever the implementation is, rather than the declaration, on the principal that people who change the implementation will be more likely to update the docs that way.

    David

> On Sep 17, 2016, at 10:24, David Cole via vtk-developers <vtk-developers at vtk.org> wrote:
> 
> For what it's worth, I've always found reading the /// style throughout to be the easiest on my brain and eyes when reading in a text editor. For some reason, it seems to be easiest to filter out a constant column of /// repeated on every line than the sprinkled start/stop signals of the other styles.
> 
> Just my 2 cents,
> David C.
> 
> 
>> On Sep 17, 2016, at 9:24 AM, Will Schroeder <will.schroeder at kitware.com> wrote:
>> 
>> For reference, I believe ITK uses /** text */
>> 
>>   /** Method for creation through the object factory. */
>> 
>> and
>> 
>>   /** A global data type for this class of equations.  Used to store
>>    * values that are needed in calculating the time step and other intermediate
>>    * products such as derivatives that may be used by virtual functions called
>>    * from ComputeUpdate.  Caching these values here allows the ComputeUpdate
>>    * function to be const and thread safe. */
>> 
>> 
>> 
>>> On Fri, Sep 16, 2016 at 2:41 PM, David E DeMarle <dave.demarle at kitware.com> wrote:
>>> Hey Folks,
>>> 
>>> I'm getting ready to replace VTK's non-standard documentation comment style with normal doxygen markup. Once we do that IDEs will generally do the right thing and we can all more easily edit the headers and get exactly what we expect.
>>> 
>>> Before I make the big initial conversion commit, what specific doxygen flavor do people prefer?
>>> 
>>> /*! and //! vs /** and /// 
>>> all c-style (/*) or all c++ style (//) or mixed OK?
>>> for c-style, leading *'s or not in continuation lines
>>> 
>>> thanks
>>> 
>>> David E DeMarle
>>> Kitware, Inc.
>>> R&D Engineer
>>> 21 Corporate Drive
>>> Clifton Park, NY 12065-8662
>>> Phone: 518-881-4909
>>> 
>>> _______________________________________________
>>> Powered by www.kitware.com
>>> 
>>> Visit other Kitware open-source projects at http://www.kitware.com/opensource/opensource.html
>>> 
>>> Search the list archives at: http://markmail.org/search/?q=vtk-developers
>>> 
>>> Follow this link to subscribe/unsubscribe:
>>> http://public.kitware.com/mailman/listinfo/vtk-developers
>>> 
>>> 
>> 
>> 
>> 
>> -- 
>> William J. Schroeder, PhD
>> Kitware, Inc. - Building the World's Technical Computing Software
>> 28 Corporate Drive
>> Clifton Park, NY 12065
>> will.schroeder at kitware.com
>> http://www.kitware.com
>> (518) 881-4902
>> _______________________________________________
>> 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
> _______________________________________________
> Powered by www.kitware.com
> 
> Visit other Kitware open-source projects at http://www.kitware.com/opensource/opensource.html
> 
> Search the list archives at: http://markmail.org/search/?q=vtk-developers
> 
> Follow this link to subscribe/unsubscribe:
> http://public.kitware.com/mailman/listinfo/vtk-developers
> 
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://public.kitware.com/pipermail/vtkusers/attachments/20160917/316b4f85/attachment.html>