Re: [pygccxml-development] pyplusplus status

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

Roman Yakovenko wrote:

>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.
>  
>
The way I handle template now and in the experimental API will require 
some changes to how module builder is created.  Specifically, module 
builder will not be able to parse immediately as a side-effect of 
__init__.  It will need to wait until later like the experimental API 
does to give the user time to call template related methods on the 
module builder.  Then when the module builder finally does start parsing 
it will have the information it needs to create the template code 
dynamically.

>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?
>  
>
I can help when I see places that need documented.  As long as you 
promise to look at the docs I add and make sure they actually reflect 
the reality of what you implemented. :)

>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.
>  
>
I would like to help with this and I would like to make it possible for 
the community to help with this.  I know writing clear documentation in 
English is difficult for you.  Luckily English is one area where I can 
help out. :)

What do you think about:
- Moving the development of this documentation to a "live" site online?
     I can contribute a wiki backend or server space for any other 
method that people recommend.
- To start, I would copy the current tutorial docs from the svn trunk.  
After that is done, the online docs would be considered the most up to date.
- Letting everyone (you, me, Matthias, and everyone else) contribute to 
this tutorial in it's "live" format
- Make this to document that is equivalent to the pyste tutorial
- Extend this document as needed based on user feedback.  I could add 
documentation about templates, Matthiascould add docs about the 
experimental API, etc.
- When you release a version of pyplusplus, we either 1) just package up 
the current online version of the docs or 2) Copy the online docs to an 
archive section online to be the stable docs for the release, then point 
everyone to those docs for that release version.

Roman, Matthias, everyone: what do you think?  would this be workable 
and acceptable?

-Allen

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