Opened 12 years ago

Last modified 9 months ago

#263 new defect

python doccomments only show information for one overloaded form

Reported by: Richard Boulton Owned by: Richard Boulton
Priority: low Milestone: 1.5.0
Component: Documentation Version: git master
Severity: minor Keywords: GoodFirstBug
Cc: Blocked By:
Blocking: Operating System: All

Description (last modified by Olly Betts)

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.

Change History (7)

comment:1 by Olly Betts, 12 years ago

Description: modified (diff)
Milestone: 1.1.01.1.1

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

comment:2 by Olly Betts, 11 years ago

Milestone: 1.1.11.1.4

Triaging milestone:1.1.1 bugs.

comment:3 by Olly Betts, 11 years ago

Component: OtherDocumentation
Priority: normallow

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).

comment:4 by Olly Betts, 11 years ago

Milestone: 1.1.41.2.0

Bumping to stay on schedule.

comment:5 by Olly Betts, 8 years ago

Milestone: 1.2.x1.3.x

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

comment:6 by Olly Betts, 5 years ago

Milestone: 1.3.x1.4.x

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.

comment:7 by Olly Betts, 9 months ago

Keywords: GoodFirstBug added
Milestone: 1.4.x1.5.0
Version: SVN trunkgit master

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.

Note: See TracTickets for help on using tickets.