Re: %feature("docstring") syntax

Hi all,

Not sure how I missed it - details are given in http://www.swig.org/Doc4.0/SWIGDocumentation.html#Customization_features

The %feature directive can be used with different syntax. The following are all equivalent:

%feature("except") Object::method { $action };
%feature("except") Object::method %{ $action %};
%feature("except") Object::method " $action ";
%feature("except", "$action") Object::method;

So using the following syntax:

%feature("docstring")
 "Adjust the rect to fit the width and height. Returns cellsize of rect."
double fit(int width, int height) {
    return  msAdjustExtent(self, width, height);
} 

Adds the docstring to the "fit" function, but then needs to be cleared afterwards or it will apply to all following functions. 
I believe the correct syntax should be:

%feature("docstring") fit
 "Adjust the rect to fit the width and height. Returns cellsize of rect.";
double fit(int width, int height) {
    return  msAdjustExtent(self, width, height);
} 

It would be nice to be able to attach the docstring without having to repeat the function name declared immediately afterwards. 

Seth

--
web:http://geographika.co.uk
twitter: @geographika

On Mon, Jun 8, 2020, at 10:13 PM, Seth G wrote:
> Hi all,
> 
> A quick question on the syntax for %feature("docstring"). From the docs 
> at http://www.swig.org/Doc4.0/Python.html#Python_nn71
> 
> "In addition to the autodoc strings described above, you can also 
> attach any arbitrary descriptive text to a node in the parse tree with 
> the "docstring" feature. "
> 
> Most of the SWIG tests use the following syntax:
> 
> %feature("docstring")  MyObject::x "float The x value.";
> 
> However the simply adding a docstring prior to a function also seems to 
> produce the correct output:
> 
>     %feature("docstring")
>     "Adjust the rect to fit the width and height. Returns cellsize of rect."
>     double fit(int width, int height) {
>         return  msAdjustExtent(self, width, height);
>     } 
> 
> In a search on GitHub I've also seen the following form:
> 
> %feature("docstring", "A docstring in the brackets") myFunction
> 
> And also sometimes there are semicolons at the end and sometimes not. 
> 
> Are all the above examples valid?
> I'm happy to expand the docs with a pull request if anyone can provide 
> clarifications.
> Thanks,
> 
> Seth

> --
> web:http://geographika.co.uk
> twitter: @geographika
> 
> 
> _______________________________________________
> Swig-user mailing list
> [email protected]
> https://lists.sourceforge.net/lists/listinfo/swig-user
>