[pyicu-dev] towards release 1.0

[Andi Vajda]

  Hi Friedel,

> On Apr 1, 2010, at 0:47, F Wolff <friedel at translate.org.za> wrote:
>
>> Someone who doesn't know C++ might find the C++ docs hard to read.
>> For
>> example, the BreakIterator currently has the docstring
>> "t_breakiterator
>> object", and the for its  __init__() I get
>> x.__init__(...) initializes x; see x.__class__.__doc__ for signature
>>
>> t_breakiterator isn't even mentioned in the C++ docs, so this is
>> doubly
>> confusing.
>
> That's a bug in the macro I use to generate the Python C type. The
> docstring, which is worthless at the moment, should at least use the
> correct classname.

That's now fixed in trunk.

>> I'm sure it is more work to do this, but will make the library more
>> useful, so it is a suggestion, and I'm offering help to do some of
>> this.
>> An example of how to do this (if it is agreed to be useful) will
>> probably get me on my way quicker.
>
> Ok, let me put an example together. This makes sense.

I added a new Python file called docs.py that includes a few examples on how 
to set a docstring on a PyICU C++ class wrapper, its constructor or any of 
its methods. I included a few doc strings plainly and shamelessly copied 
from the ICU C++ APi web site. Note that not all methods behave exactly as 
documented with regards to what the type of parameters, which parameters are 
optional and what the type of the return value is. For an exact story on 
each of these, careful examining of the corresponding wrapper code is 
necessary. I hope that the boilerplate coding pattern use there can become
self-evident after a few hours of examination.

Let me know if you have questions.

Thank you for taking an interest in this !

Kind regards,

Andi..