Geoff Worboys writes:
[...] > What's basically happening is that doxygen thinks that the > instantiation, vectorObj<constraint> is a discrete class, > then complains that it can't find the documentation for any > of its class methods. The only reason that doxygen knows > about what's in vectorObj is because it reads the tagfile > from the project where the vectorObj template gets declared. > I think that's what's happening, but it doesn't seem to be > happening for everything that's imported from the tagfile, > only for the class that gets instantiated as a superclass.Well, technically, I suppose that vectorObj<constraint> is becoming a discrete class at that point (unless there has been reason to instantiate it previously) - though obviously we don't really expect doxygen to see it that way. What is INHERIT_DOCS set to? The default is YES I think, and so that would presumably make doxygen go looking. (Perhaps the tag file knows enough to find the class exists, but is unable to resolve the methods for some reason.)
Yes, INHERIT_DOCS=YES.The thing is, though, is that vectorObj<constraint> is not really a discrete class, in C++. It's an instance of a template class. All methods defined in the template become the same methods in the class instance. Same parameters, etc… Everything that's documented for the template class becomes applicable to the template class instance.
What would be truly a discrete class is a specialized template declaration. This would look something like
template class vectorObj<constraint> {
// …
};
It would define its own methods, which have absolutely nothing to do with
anything defined for template<typename whatever> class vectorObj. This is
really a discrete class on its own.
And to make things interesting, a partial template specialization would be a discrete template class that doesn't have anything to do with the original template, something like
template<typename value_type>
class vectorObj<std::vector<value_type>> {
// …
};
But a simple
class snorkle: public vectorObj<constraint> {
// …
};
does not really create a discrete class, but creates and instance of the
template class.
I think I understand what's happening here. Yes, snorkle does inherit all methods from its superclass. With INHERIT_DOCS=YES we are requesting documentation of vectorObj's methods as snorkle's own methods. But, what's being inherited here are the template class vectorObj's methods, not some discrete, separate class named vectorObj<constraint>. That's what doxygen is seeing, and it's seeing the methods that are inherited, thanks to the tagfile I'm importing via TAGFILES. But, doxygen is not seeing any documentation for those inherited methods, of course, because they're in external header files. That's the whole purpose of tagfiles, to split up the documentation, but still link to them. But, you can inherit from stuff declared externally.
I think that what we really want to happen here is for GENERATE_TAGFILE to also include the raw, unformatted documentation in the exported tagfile. So, when you bring it in via TAGFILES, doxygen would know the documentation for the external classes that get imported, and can grab them via INHERIT_DOCS.
I'm not overriding or redefining the inherited methods in the subclass. So, having the inherited methods documented isn't really a big deal; just suppressing warnings for imported, and undocumented, stuff would also be fine.
Or, one hack would be for doxygen to generate a link to the supeclass's methods, when a subclass inherits methods from a class that's imported, just to a \see parent::method in lieu of missing documentation.
pgpMxKCICc17V.pgp
Description: PGP signature
------------------------------------------------------------------------------ How ServiceNow helps IT people transform IT departments: 1. A cloud service to automate IT design, transition and operations 2. Dashboards that offer high-level views of enterprise services 3. A single system of record for all IT processes http://p.sf.net/sfu/servicenow-d2d-j
_______________________________________________ Doxygen-users mailing list Doxygen-users@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/doxygen-users
