Re: [pygccxml-development] pyplusplus status

[Roman Y. <rom...@gm...>]

On 7/19/06, Allen Bierbaum <al...@vr...> wrote:
> Don't forget to review the Pyste API.  I hate to say it, but it is a
> reality of software that anything that is easy to do in the original
> tool (Pyste) but hard to do in the new tool (pyplusplus) will hurt
> adoption of the the new software package.  Pyplusplus not only has to be
> able to do more it has to be able to still do everything Pyste does and
> do it just as easily.

I did it. py++ is missing next functionality:

1. py++ is missing template functionality:
    http://boost.org/libs/python/pyste/doc/templates.html

    If you or Matthias will contribute the code, py++ will also have
this functionality.

2. Wrappers
    http://boost.org/libs/python/pyste/doc/wrappers.html

    py++ provides this functionality, but user have to understand code creators.
    This will be fixed in next 2 weeks. With one line of code you will
be able to
    add code to:
    1. declaration section of the module ( before BOOST_PYTHON_MODULE )
    2. registration section ( within BOOST_PYTHON_MODULE )
    3. declaration section within source file, that exposes some class

    If I will get positive comments about new functionality, I will
extend it to free
    functions.


> You are probably right that the big thing I am missing is complete
> documentation.  For example a table with all the type traits, how to
> call them, and what they return.

What is wrong with this documentation
http://language-binding.net/pygccxml/apidocs/pygccxml.declarations.type_traits-module.html
?

> Similarly with the api for
> lookup/search, documentation of all the methods, all the params,

It is a huge effort for me really. Now, when you understand how this
lookup/search/query api works, can you add documentaton to source
file?
Thanks.

> and all the matchers.

What is wrong with this documentation:
http://language-binding.net/pygccxml/apidocs/index.html
?

More over in most cases you don't have to use matchers at all. Query API
will does it for you.

>(once again, just a table that lists everything in one
> place with a short description would be helpful).  I know from
> experience what source files to look in, but new users don't know this.

I agree with you.

> This could be helped a lot by just having a complete tutorial with pages
> that have these tables.

I am going to build documentation, similar to Pyste. It will describe
functionality
of py++ and how I expect it should be used.



> >
> >> If the query api was more completely documented in a tutorial form (so
> >> newbies don't have to delve deeply into the reference docs), then I
> >> think we would be on much better footing here.
> >
> >
> > What is wrong with this
> > http://language-binding.net/pygccxml/query_interface.html
> > tutorial. If you understand how to use "member_function(s)" , you
> > understand all others.
> >
> Yes, but you have to know what all the "others" are and that they take
> the same parameters.  Once again, I am not saying we are too far from
> this, but there is still a disconnect for a new user.

I will add "others" to the documentation. Thanks for the tip.

> > I don't agree with you. I think, the project does not have enough
> > documentation.
> > If I will describe every public function in terms of: precondition,
> > post condition,
> > arguments and return value, then you will almost never will have to
> > look to source code.
> >
> But even then you are talking about reference documentation.  There
> needs to be some starting point that lets the user know the capability
> exists.  Then this can be used as a launching point to looking for the
> detailed documentation.

What is wrong with this tutorial
http://www.language-binding.net/pyplusplus/tutorials/module_builder/module_builder.html
?

> I could be totally wrong here though.  I would love for you to prove me
> wrong.  I don't care how we get there or who's ideas work, just as long
> as new users can pick up, understand, and use pyplusplus easily.

No, you are right. I need to concentrate my attention on documentation.


-- 
Roman Yakovenko
C++ Python language binding
http://www.language-binding.net/