#1390 Documentation should emphasize declaration order
There are many cases where SWIG directives have to be supplied in a specific order with respect to the code and other directives, or else SWIG will effectively ignore the directive without producing a warning. The documentation should be enhanced in certain areas to emphasize this point.
For example, section 16.8 gives the following example:
// A template
template<class T> class Foo {
public:
// A member template
template<class S> T bar(S x, S y) { ... };
...
};
// Expand a few member templates
%extend Foo {
%template(bari) bar<int>;
%template(bard) bar<double>;
}
// Create some wrappers for the template
%template(Fooi) Foo<int>;
%template(Food) Foo<double>;
What is not mentioned is that the three parts of the example must be placed in this particular order; The %extend block doesn't work unless it is placed after the %template(Foo*) directives, and the %template(Foo*) directives must be placed after the declaration of Foo.
(curious side note: the following DOES work:)
// after template<class T> class Foo { ... };
%template(Fooi) Foo<int>;
%template(Food) Foo<double>;
%extend Foo<int> {
%template(bari) bar<int>;
%template(bard) bar<double>;
}
Section 5.4.7 doesn't mention that %ignore must go before the declaration to be ignored, and although it does say "placement of the %rename directive is arbitrary as long as it appears before the declarations to be renamed", I think this point needs more emphasis in the documentation because of the fact that
- SWIG doesn't warn you if you do it wrong, and
- If you use certain orderings in a wrapper that involves %template, SWIG will honor the user's directives most of the time but occasionally will stop working (see my bug report 2503171)
Perhaps there should be a section dedicated to teaching the ordering rules, that would list each directive in a table (including common macros like %attribute) and the preferred order.
In addition to covering directives, it should talk about ordering between C/C++ directives. For example, it should say whether SWIG is able to handle
class Derived : public Base {...};
class Base {...};
or
void f(Foo* g);
struct Foo { ... };
or
void f(Integer* g);
typedef int Integer;
Personally, I would like so see some discussion of how SWIG works internally and how this internal functioning impacts the required ordering.
Ticket moved from /p/swig/feature-requests/62/