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

[Bradley Lowekamp]

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
>> 
>> 
> 

========================================================
Bradley Lowekamp  
Lockheed Martin Contractor for
Office of High Performance Computing and Communications
National Library of Medicine 
blowekamp at mail.nih.gov


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