Re: [pygccxml-development] pyplusplus status

[Allen B. <al...@vr...>]

Roman Yakovenko wrote:

> On 7/18/06, Allen Bierbaum <al...@vr...> wrote:
>
>> I think the keywords here are "most tasks".   I think we are already
>> close to being able to do most tasks with the higher-level API. I just
>> don't think the high-level API allows people to do everything as easily
>> as they could with Pyste or the experimental API that Matthias is using.
>
>
> I will study Matthias API and write here my thoughts.

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 would also say the simple API would require limited to no use of
>> pygccxml directly.  This may be one of the areas that gets me the most
>> because I don't always know where to look in pygccxml to do what I want.
>
>
> I thought that pygccxml is pretty simple project. In 99% of use case you
> have to understand only declarations package. I will try to improve
> documentation
> for the package. Please say what information you are missing?

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. Similarly with the api for 
lookup/search, documentation of all the methods, all the params, and all 
the matchers.  (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.  
This could be helped a lot by just having a complete tutorial with pages 
that have these tables.

>
>> 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 keep using the term "tutorial", but maybe the more appropriate term 
would be "user's guide".  What I think is needed is something similar to 
the Pyste documenation and the Boost.Python Tutorial.  Something that 
shows the user-level API that can be used to accomplish most tasks.  It 
should have reference to where to go for lower-level detail, but it 
should stand on it's own as a useful resource.

>> >
>> > power - modifying directly code creators tree. This is really the
>> > "dark" area of the project,
>> > but I have an idea how to simplify it and of course I will write a
>> > documentation that will
>> > explain it.
>>
>> I would also add using anything in pygccxml that requires understanding
>> of how pygccxml is implemented and using any of pygccxml that is not
>> documented in a tutorial.  Basically, if the user has to read the code
>> to understand or find what they need to do, then that is not part of the
>> simple interface.
>
>
> 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. 

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.

-Allen