#62 Documentation should emphasize declaration order

David Piepgrass

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 {
// 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 {...};


void f(Foo* g);
struct Foo { ... };


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.