Opened 11 years ago

Last modified 4 years ago

#263 new defect

python doccomments only show information for one overloaded form

Reported by: richard Owned by: richard
Priority: low Milestone: 1.4.x
Component: Documentation Version: SVN trunk
Severity: minor Keywords:
Cc: Blocked By:
Blocking: Operating System: All

Description (last modified by olly)

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

Either: 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, 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 (6)

comment:1 Changed 11 years ago by olly

  • Description modified (diff)
  • Milestone changed from 1.1.0 to 1.1.1

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

comment:2 Changed 10 years ago by olly

  • Milestone changed from 1.1.1 to 1.1.4

Triaging milestone:1.1.1 bugs.

comment:3 Changed 10 years ago by olly

  • Component changed from Other to Documentation
  • Priority changed from normal to low

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 Changed 10 years ago by olly

  • Milestone changed from 1.1.4 to 1.2.0

Bumping to stay on schedule.

comment:5 Changed 7 years ago by olly

  • Milestone changed from 1.2.x to 1.3.x

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

comment:6 Changed 4 years ago by olly

  • Milestone changed from 1.3.x to 1.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.

Note: See TracTickets for help on using tickets.