doxygen-develop

[Doxygen-develop] Support for C++ Template Classes

[Dirk R. <re...@ca...>]

	Hi everybody,

we're using templates pretty heavily, and some of their methods don't go 
well with doxygen.

We use a lot of template base classes that are specialized for different 
types (similar to vector<int>). To simplify things we use a lot of 
typedefs (like typdef vector<int> ivec). But given that they're just 
typedefs they don't show up in the class list or the inhertiance 
hierarchy, even though for all practical reasons they're classes. Any 
ideas how to make them show up as classes in an easy way? Right now the 
place to find them is in the namespace list, and that's not very intuitive.

The second problem, and that is hairier, is using mixins or traits. The 
basic idea is that classes are constructed as templates and are derived 
from one of their template arguments, or one of the arguments internal 
types. I can understand that this would be very hard to do right, but I 
would like to take a look at it anyway, and maybe kludge it. Can anybody 
give me a hint where and how doxygen stores template classes?

Thanks

	Dirk

Re: [Doxygen-develop] Support for C++ Template Classes

[Ethan Tira-T. <ej...@an...>]

> We use a lot of template base classes that are specialized for  
> different types (similar to vector<int>). To simplify things we use  
> a lot of typedefs (like typdef vector<int> ivec). But given that  
> they're just typedefs they don't show up in the class list or the  
> inhertiance hierarchy, even though for all practical reasons  
> they're classes.

I just want to add my vote for this as well -- in our case, we have a  
templated class:
template<class T, const char* mcName=defName, const char*  
mcDesc=defDesc, bool completes=true> class MCNode;

And then for the "simple" cases we only need to pass template  
parameters:
typedef MCNode<TailWagMC,defTailWagNodeName,defTailWagNodeDesc,false>  
TailWagNode;
typedef  
MCNode<HeadPointerMC,defHeadPointerNodeName,defHeadPointerNodeDesc>  
HeadPointerNode;
...

And for "harder" issues we can uses subclasses instead:
class LedNode : public MCNode<LedMC> { /*...*/ }

So the trick is, LedNode shows up in the class listing as expected,  
but TailWagNode and HeadPointerNode don't.  Technically, this is  
accurate since they're really just typedefs, but from a user  
standpoint, there's no difference -- the user is going to look in the  
class listing to see what's available and not know the 'type' exists.

Perhaps there could be a keyword to treat a typedef as a subclass  
instead of "just" a typedef?

> Any ideas how to make them show up as classes in an easy way? Right  
> now the place to find them is in the namespace list, and that's not  
> very intuitive.

Our workaround is to modify the code to use a "real" subclass  
instead, but that's less than ideal, as it causes additional overhead  
and requires the subclass to replicate all of the constructors of the  
base class to forward them through (maintenance issue).

-ethan

Re: [Doxygen-develop] Support for C++ Template Classes

[Jens M. <ju...@ma...>]

Am 27.09.2006 um 22:14 schrieb Ethan Tira-Thompson:

>> We use a lot of template base classes that are specialized for  
>> different types (similar to vector<int>). To simplify things we  
>> use a lot of typedefs (like typdef vector<int> ivec). But given  
>> that they're just typedefs they don't show up in the class list or  
>> the inhertiance hierarchy, even though for all practical reasons  
>> they're classes.
>
> I just want to add my vote for this as well -- in our case, we have  
> a templated class:
> template<class T, const char* mcName=defName, const char*  
> mcDesc=defDesc, bool completes=true> class MCNode;
>
> And then for the "simple" cases we only need to pass template  
> parameters:
> typedef  
> MCNode<TailWagMC,defTailWagNodeName,defTailWagNodeDesc,false>  
> TailWagNode;
> typedef  
> MCNode<HeadPointerMC,defHeadPointerNodeName,defHeadPointerNodeDesc>  
> HeadPointerNode;
> ...
>
> And for "harder" issues we can uses subclasses instead:
> class LedNode : public MCNode<LedMC> { /*...*/ }
>
> So the trick is, LedNode shows up in the class listing as expected,  
> but TailWagNode and HeadPointerNode don't.  Technically, this is  
> accurate since they're really just typedefs, but from a user  
> standpoint, there's no difference -- the user is going to look in  
> the class listing to see what's available and not know the 'type'  
> exists.
>
> Perhaps there could be a keyword to treat a typedef as a subclass  
> instead of "just" a typedef?
>
>> Any ideas how to make them show up as classes in an easy way?  
>> Right now the place to find them is in the namespace list, and  
>> that's not very intuitive.
>
> Our workaround is to modify the code to use a "real" subclass  
> instead, but that's less than ideal, as it causes additional  
> overhead and requires the subclass to replicate all of the  
> constructors of the base class to forward them through (maintenance  
> issue).

You could, of course, make them subclasses for doxygen only, e.g.

//! nodes for the tail-wag thingy
#if __DOXYGEN__
	class TailWagNode : public  
MCNode<TailWagMC,defTailWagNodeName,defTailWagNodeDesc,false> {};
#else
	typedef  
MCNode<TailWagMC,defTailWagNodeName,defTailWagNodeDesc,false>  
TailWagNode;
#endif

This is still tedious (and some additional support in doxygen for  
this kind of problem would surely be great), but at least you don't  
have the additional overhead in your application and only minimally  
more maintenance issues.

</jum>