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

[Arnaud GELAS]

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

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