python doccomments only show information for one overloaded form

[Richard Boulton]

If a function or method in the C++ headers has documentation comments for multiple overloaded forms, the documentation comments extracted by doxygen and doxy2swig.py only contain the text from the final one of these forms.

Either: doxy2swig.py should combine the comments for all the possible overloaded forms, or we should provide manually written overrides for all cases where these forms exist.

If the latter option is chosen, doxy2swig.py should complain if any overloaded forms exist for which there are multiple comments but no manual override.

This can lead to users getting confused (the comment for open_remote is particular confusing, since it only mentions the progsrv backend), and it would be nice to tidy this up for 1.1.0, so marking for that milestone for now. I'm not desperately worried if it slips, though.

[Olly Betts]

Bumping milestone to 1.1.1 as there's no patch yet and this isn't an incompatible change.

[Olly Betts]

Triaging milestone:1.1.1 bugs.

[Olly Betts]

This could be done at any point, but it's an annoying problem (and Enrico hit it only a day or two ago, so it is affecting users).

[Olly Betts]

Bumping to stay on schedule.

[Olly Betts]

This needs to be addressed in trunk first, and then we can consider backporting.

[Olly Betts]

This isn't worth holding up 1.4.0 for.

SWIG support for parsing doxygen comments looks like it might finally get merged, which could provide another route for getting python doccomments.

[Olly Betts]

The SWIG support for parsing doxygen comments was merged in SWIG 4.0.0:

​http://swig.org/Doc4.0/Doxygen.html

It would be interesting to try using that instead of the doxy2swig.py script.

[Olly Betts]

Postponing. Could likely be backported to a stable release once implemented.