[Xapian-tickets] [Xapian] #263: python doccomments only show information for one overloaded form

[Xapian]

#263: python doccomments only show information for one overloaded form
---------------------+------------------------------------------------------
 Reporter:  richard  |        Owner:  richard  
     Type:  defect   |       Status:  new      
 Priority:  normal   |    Milestone:  1.1.1    
Component:  Other    |      Version:  SVN trunk
 Severity:  minor    |   Resolution:           
 Keywords:           |    Blockedby:           
 Platform:  All      |     Blocking:           
---------------------+------------------------------------------------------
Changes (by olly):

  * milestone:  1.1.0 => 1.1.1


Old description:

> 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 chose, 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.

New description:

 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.

--

Comment:

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

-- 
Ticket URL: <http://trac.xapian.org/ticket/263#comment:1>
Xapian <http://xapian.org/>
Xapian