[pygccxml-development] Updated status

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

A apologize in advance, this e-mail is going to be a little random 
because it is based on my notes from this afternoon.  I started trying 
to move the pypp_api interface over the the new codebase and these are 
the things I have run into right away.

- Calling parser changed a bit.

There seems to be a new interface to calling the project parser.  I 
think I just need to add a decl wrapper factory but I am not for sure.  
Roman?

- How am I supposed to use the decl_wrappers?

I am trying to parse with the project reader and then I was expecting 
that the returned decls would actually be the wrappers/decorators for 
the decls.  Is this how it is supposed to work?

- Code complexity: The new decorators does look like a LOT of additional 
code for what could be done with some grafted flags.  Not really a 
question, more of a comment.  I really think the codebase could be 
simplified a lot.  For me at least all the property usage seems like a 
lot of extra code to read through and maintain for very little payoff.

- What is module_builder_t for?  Do I have to use it?  It looks like 
Roman's stab at the higher-level interface but what do I need to copy 
from there into pypp_api.

- Why did call policies move to the wrapper module?  Those still seem 
like code_creators.

- Decl wrappers don't seem to support everything I needed/added with the 
decorators.

Specifically, how can I add custom creators?  In my flag-based version I 
could add a list of code creators that would automatically be added on 
when the creator class build the code creators for a decl. 

- What are all the options that have been added to the wrappers? (see 
documentation below)

- I think Logger should probably use info() for most of the current 
output.  Why put time and level name in log output?

My original goal with this output was to have verbose output for users 
not to provide a debug log to a log file on errors. Any objections to 
making the output look cleaner by making the info() filter just output 
the text instead of all the header information?

- Comments: We *really* need comments and documentation for the classes 
and methods in pygccxml and pyplusplus.  I think Matthias and I could 
help out by pointing to areas of the code and saying in our very nicest 
voice "Roman, please please document this".

Toward this goal (and following up on Matthias's comments from last 
week), I started looking at what it would take to generate documentation 
using epydoc and restructuredtext.  I added a script in 
"experimental/docs/generate_all_docs.py" that will call epydoc with what 
I think are the correct parameters to generate html documentation.  I 
also started converting pypp_api over to use restructured text for 
documentation. The only problem is that it looks like the tags/fields I 
am using are not being recognized correctly (ex: params, args, etc).  
According to the docs I am doing things correctly but it is just not 
working.  If either of you have experience with this tool please take a 
look and let me know if I am doing something wrong.

Does this seem like a good direction for documentation?  I know we can 
document classes and methods using this, do we want to document the 
usage of the modules like this as well?  (it is supported but do we want 
that type of documentation in the code?)

That is about all I have for now.  Until I find out more about the 
decl_wrapper's and their use I am at a stand still. :(

Thanks,
Allen