#915 %typemap(out) matching docs

[Dustin J. Mitchell]

Somewhere, somehow, we should describe the matching done by (out) typemaps. Since typemaps are documented per language module, that probably means copy-pasting the same paragraph into every language module?

[Dustin J. Mitchell]

1948099.patch (mentions limitations, too)

[Dustin J. Mitchell]

Logged In: YES
user_id=7446
Originator: YES

File Added: 1948099.patch

[Olly Betts]

Logged In: YES
user_id=14972
Originator: NO

Is it deliberate that out typemaps don't allow qualifying with a classname? If that's a bug, we should fix it rather than document the misbehaviour.

[Dustin J. Mitchell]

Logged In: YES
user_id=7446
Originator: YES

Unfortunately, that's a bit above my pay grade..

Can you commit the docs fix now and leave the bug open for the bugfix?

[Olly Betts]

Sorry, looks like I dropped the ball on this. I think I must have intended to investigate a bit first, but I've only just done so.

It seems the bug you hit has been fixed since. Testing with SWIG 4.0.2:

$ cat test.i
%module test
%typemap(out) char *getbytestring1 {
   ... // will be applied CASE1
}
%typemap(out) char *Foo::getbytestring2 {
   ... // not matched CASE2
}
class Foo {
public:
    %typemap(out) char *Foo::getbytestring3 {
       ... // not matched CASE3
    }
    %typemap(out) char *getbytestring4 {
       ... // not matched CASE4
    }
    char *getbytestring1(void);
    char *getbytestring2(void);
    char *getbytestring3(void);
    char *getbytestring4(void);
};
$ swig -c++ -python test.i
$ grep 'wrap_Foo_getbytestring.(\|CASE' test_wrap.cxx 
SWIGINTERN PyObject *_wrap_Foo_getbytestring1(PyObject *SWIGUNUSEDPARM(self), PyObject *args) {
    ... // will be applied CASE1
SWIGINTERN PyObject *_wrap_Foo_getbytestring2(PyObject *SWIGUNUSEDPARM(self), PyObject *args) {
    ... // not matched CASE2
SWIGINTERN PyObject *_wrap_Foo_getbytestring3(PyObject *SWIGUNUSEDPARM(self), PyObject *args) {
    ... // not matched CASE3
SWIGINTERN PyObject *_wrap_Foo_getbytestring4(PyObject *SWIGUNUSEDPARM(self), PyObject *args) {
    ... // not matched CASE4

So all the typemaps have matched and been applied to the correct methods.

The first hunk is no longer useful, but I've pushed a slightly tweaked version of the last hunk:

Typemaps are matched using both a type and a name (typically the name of an  
argument, but in the case of <tt>out</tt> typemaps, the name of a function,   
qualified by the class name if it's a class method).  For a given <tt>TYPE
NAME</tt> pair, the following rules are applied, in order, to find a match.  
The first typemap found is used.

(I've noted the name is qualified with the class name since it now reliably seems to be; also corrected "a argument" to "an argument" which was wrong in the existing text.)