Add structured support for templates?

[EricCousineau-TRI]

This is an upstream version of CastXML/pygccxml#121, towards RobotLocomotion/drake#13670

I've reviewed #20 (and very briefly #11), but I would still like to see if it's possible to get some structured information from templates (e.g. parameter names and values w.r.t. the canonical decl/def.).

As mentioned in the pygccxml issue, I would like to see how much can be automated, and I would still like to be able to parse templates themselves, and possibly even cross-reference pure instantiations explicitly.

Given that libclang exposes this information (albeit a tad awkwardly), I'm sure at least some portion of it can be exposed here?

From looking at clang, seems like it would exposable, as say TemplateClass, TemplateFunction, TemplateMethod, etc., somewhere near here?

CastXML/src/Output.cxx

Lines 522 to 523 in 8625aed

	void OutputClassTemplateSpecializationDecl(
	clang::ClassTemplateSpecializationDecl const* d, DumpNode const* dn);

\cc @jamiesnape

[EricCousineau-TRI]

Er, nothing special for methods, so I guess they fold under functions with a __thiscall__ type thing?
https://clang.llvm.org/doxygen/classclang_1_1TemplateDecl.html

[bradking]

Support for uninstantiated templates has never been a design goal (see #153 (comment)) mainly because it hasn't been necessary for automated wrapper generation. However, support for documentation tools and perhaps some way of automatically generating instantations for wrapping may be sufficient justification.

seems like it would exposable, as say TemplateClass, TemplateFunction, TemplateMethod, etc.

Bikeshedding: C++ terminology would prefer the names ClassTemplate, FunctionTemplate, etc. I don't know why Clang internals switch that order.

Design considerations include:

• Representing member relations.
• Representing relations among the primary template, partial, and full specializations.
• Referencing the templates from their instantiations.
• Selection of which templates to include in the output based on the --castxml-start option.

Inclusion of templates in the output should be enabled explicitly by option because in some use cases they are not relevant.

[bradking]

For reference, our current documentation has a FAQ Entry about this. The answer includes some notes relevant here.

[EricCousineau-TRI]

Thanks! All of that makes sense, but just one question:

Representing member relations.

Can I ask what you mean by this?

[bradking]

By "representing member relations" I meant things like member templates inside both non-templates and other templates. If we list a template as a member of a non-template class, that could confuse existing clients. We likely need a separate attribute to represent members that are templates.

[EricCousineau-TRI]

FTR Here's a xref to the autopybind11 issue with a discussion btw Brad and me:
https://gitlab.kitware.com/autopybind11/autopybind11/-/issues/92#note_804730

So yeah, I think we can close this issue for now unless I really run into a feature or performance show-stopper (e.g. C++ -> XML -> pygccxml, performance impact from having to do fully-scoped name lookups for template parameters, after parsing the template name, etc.).

[bradking]

Okay, we'll close this in favor of other approaches discussed over there.