Re: [pygccxml-development] Updated status

[Matthias B. <ba...@ir...>]

Roman Yakovenko wrote:
> On 3/6/06, Allen Bierbaum <al...@vr...> wrote:
> I started to use epydoc for pygccxml. My approach was next:
> 
> For epydoc generated documentation I used epytext. I had some problems
> with using rest. For manuals, I meen arcticles, tutorials, introduction, I use
> docutils.

That looks good to me.

> If you go to pygccxml\docs or pyplusplus\docs you will find few *.rest files.
> Also you will find script that builds documentation.
> 
> [...]
> As much as I hate automatically generated documentation [...]

Oops, really? Why is that? (at least this explains the lack of doc 
strings... ;)
Personally, I think the auto-generated docs are useful as a reference 
manual for developers and advanced users (provided that the source code 
also contains appropriate documentation which is collected by the doc 
generation tool).
I mean, what's the alternative? If you don't provide the API 
documentation right with the implementation you have to put it somewhere 
else and make sure it doesn't get out of sync...

>> > - 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".
> 
> Huston, you've got a problem :-). For me it is a huge effort to write
> documentation.
> I can not explain my self clearly. If you don't mind, I prefer to
> answer 1000 question from
> you and Matthias, but you will write documentation. Please, please, please :-)

That's a deal. But can I ask for for one thing, once there are more doc 
strings and you modify some part of the code, can you then please check 
the corresponding doc string and see if it is still valid (and adjust it 
if necessary)? All the effort would be in vain if the doc strings would 
get out of sync with the implementation after a while.
Also, when you create *new* methods/functions, could you at least 
provide some basic information such as the types of the input arguments 
and the return type (unless they are really obvious) or any precondition 
that has to be met, etc (in general, it is impossible to extract these 
things from the source code). This would already simplify the job of 
understanding the code and we might get away with a little less than 
"1000 questions"... ;-)

I've started creating a script generate_reference_manual.py in 
pygccxml/docs (based on Allen's generation script for the pyplusplus 
package). I haven't incorporated the stuff right into generate_docs.py 
because it also makes sense to run it in isolation but of course, it 
would be no problem to run that script from generate_docs.py as well.
I already converted the doc strings in my directory_cache class to 
epytext markup and also modified a few doc strings at some other places 
in the pygccxml package (so far mainly to remove the warnings/errors). 
Roman, is it ok when I commit these things?

I assume you two are also subscribed to the commit list, right? Then it 
would be great if you, Roman, would check if the doc strings we provide 
really describe the semantics you've originally intended. And Allen, as 
I suppose you are a native English speaker (even though your surname 
kind of looks as if you were German) you could have a short glimpse over 
the doc strings to see that the grammar is not too far off. ;)

- Matthias -