[Insight-developers] kwstyle - doxygen - partial template specialization

[Arnaud GELAS]

Thanks Brad!

I forgot about the existence of this file :)!!

Can someone tell me what needs to be added in this file?

---

but you also pointed an interesting problem, for instance the functor is 
not documented but the filter is.
2 classes, only one is documented.

I can't understand why KWStyle is not complaining here!?

Arnaud


On 05/06/2011 02:50 PM, Bradley Lowekamp wrote:
> Hello,
>
>
> What about adding an exception to "Utilities/KWStyle/ITKOverwrite.txt" 
> for the problematic files?
>
> Brad
>
> On May 6, 2011, at 2:36 PM, Arnaud GELAS wrote:
>
>> Brad,
>>
>> if the documentation of EdgePotentialImageFilter was next to its 
>> declaration, you would not need to use \class!!
>> Althouh you'd get one KWStyle error, i.e.
>>
>>     Error #20 (61) comment doesn't have \class
>>
>> I have tested with the following:
>>
>> template< class TInput, class TOutput >
>> class EdgePotential
>>
>> ...
>>
>> /** \brief Computes the edge potential of an image from the image 
>> gradient.
>> *
>> * Input to this filter should be a CovariantVector image representing
>> * the image gradient.
>> *
>> * The filter expect both the input and output images to have the same
>> * number of dimensions, and the output to be of a scalar image type.
>> *
>> * \ingroup ITK-ImageIntensity
>> */
>> template< class TInputImage, class TOutputImage >
>> class ITK_EXPORT EdgePotentialImageFilter
>>
>> ---
>>
>> Note that in this particular case, it would make sense anyway to move 
>> the documentation of EdgePotentialImageFilter,
>> next to its declaration and write the documentation of the functor...
>>
>>
>> I agree that we should push push developers to use the \class command 
>> in any case, but enforcing creates problem in the documentation.
>> Relaxing this constraint would fix the documentation!!!
>>
>> Arnaud
>>
>>
>>
>> On 05/06/2011 02:19 PM, Bradley Lowekamp wrote:
>>> Arnaud,
>>>
>>> I was just looking at 
>>> ImageIntensity/include/itkEdgePotentialImageFIlter.h and I see the 
>>> following pattern ( which occurs in many of the functor filters ):
>>>
>>> ** \class EdgePotentialImageFilter
>>>  *
>>>  * \brief Computes the edge potential of an image from the image 
>>> gradient.
>>>  *
>>> ...
>>> * \ingroup ITK-ImageIntensity
>>>  */
>>> namespace Functor
>>> {
>>> template< class TInput, class TOutput >
>>> class EdgePotential
>>> {
>>> ...
>>> };
>>> } // end namespace Functor
>>>
>>> template< class TInputImage, class TOutputImage >
>>> class ITK_EXPORT EdgePotentialImageFilter:
>>>   public
>>> ...
>>>
>>>
>>> It such a case isn't the "\class" needed so that the doxygen 
>>> comments appear with the FIlter and not the functor?
>>>
>>> Brad
>>>
>>>
>>> On May 6, 2011, at 1:05 PM, Arnaud GELAS wrote:
>>>
>>>> Hi all,
>>>>
>>>> It took me a while to figure out to remove such a kind of warning 
>>>> in doxygen (for partial template specialization), and to make it 
>>>> appear correctly in doxygen:
>>>>
>>>> /home/ajg23/DOCUMENTATION/ITK_Static_Release/ITK/Modules/Core/Common/include/itkNumericTraitsCovariantVectorPixel.h:26: 
>>>> warning: the name `CovariantVector' supplied as the argument of the 
>>>> \class, \struct, \union, or \include command is not an input file
>>>> /home/ajg23/DOCUMENTATION/ITK_Static_Release/ITK/Modules/Core/Common/include/itkNumericTraitsDiffusionTensor3DPixel.h:28: 
>>>> warning: the name `DiffusionTensor3D' supplied as the argument of 
>>>> the \class, \struct, \union, or \include command is not an input file
>>>>
>>>>
>>>> Right now all specialization documentation appear in NumericTraits, 
>>>> see http://www.itk.org/Doxygen/html/classitk_1_1NumericTraits.html
>>>>
>>>> To solve this problem, we *MUST *remove /\class/ in all these files 
>>>> and document each template parameter via /\tparam/. Then it works fine!
>>>>
>>>> However KWStyle enforce all class to have /\class/...
>>>>
>>>> After running some experiments, it appears that /\class/ is not 
>>>> mandatory for any class; doxygen will automatically generate the 
>>>> class documentation even if there is no \class marker.
>>>>
>>>> So would it be possible to relax this constraint in KWStyle in 
>>>> order to improve doxygen documentation?
>>>>
>>>> Thanks,
>>>> Arnaud
>>>> <ATT00001..txt>
>>>
>>> ========================================================
>>> Bradley Lowekamp
>>> Lockheed Martin Contractor for
>>> Office of High Performance Computing and Communications
>>> National Library of Medicine
>>> blowekamp at mail.nih.gov <mailto:blowekamp at mail.nih.gov>
>>>
>>>
>>
>
> ========================================================
>
> Bradley Lowekamp
>
> Lockheed Martin Contractor for
>
> Office of High Performance Computing and Communications
>
> National Library of Medicine
>
> blowekamp at mail.nih.gov <mailto:blowekamp at mail.nih.gov>
>
>
>

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://www.itk.org/mailman/private/insight-developers/attachments/20110506/09a5b252/attachment.htm>