[pyicu-dev] towards release 1.0

[F Wolff]

Op Wo, 2010-03-31 om 15:19 -0700 skryf Andi Vajda:
> On Mar 31, 2010, at 14:49, F Wolff <friedel at translate.org.za> wrote:
> 
> > Op Wo, 2010-03-31 om 10:29 -0700 skryf Andi Vajda:
> >> On Wed, 31 Mar 2010, F Wolff wrote:

> > The first thing that strikes me, is that I'll need to get familiar  
> > with
> > the C API before I can use this.
> > Would it be possible to get some of the
> > C documentation into the docstrings?  It would make it more useful in
> > itself, and will be more accessible to programmers who don't know C  
> > that
> > well.
> 
> The README file explains where to find the C++ API docs (as opposed to  
> the C one, PyICU wraps ICU C++ classes) and how they correspond to the  
> python wrappers. It also explains how pythonic features, such as  
> iterators, string coversion, etc... are supported.
> If you find holes or bugs in this file, please send them along.
> As for copying the ICU docs, hmmm, patches are welcome.
> 
> > Talking about PEPs - just checking:  do we want to keep the camel case
> > capitalisation to stay close to the C library?
> 
> The wrapped class names and method names match exactly, where  
> possible, the ICU C++ ones. This is so that api docs can be matched  
> against, for example. The C api functions are _not_ wrapped by PyICU.
> 
> > I might be able to help with some of this if I have a good example  
> > to go
> > by. Is this something that everybody wants?
> 
> What are you actually proposing ?
> 
> Andi..

Sorry about the C/C++ mixup.  What I am proposing is a way to ensure
that "pydoc icu" will be useful and as self-contained as we can. I get
docstrings in my editor for the libraries I use, so having the
docstrings as complete as possible makes the python bindings even more
useful.

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.

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.

Regards
Friedel

--
Recently on my blog:
http://translate.org.za/blogs/friedel/en/content/provisionaly-done-localisation-guide-amharic