Re: [pygccxml-development] Updated status

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

Matthias Baas wrote:

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

Agreed.  docstrings are good for reference documentation and are also a 
good way for the developer to communicate their implementation ideas to 
other developers (and themselves when they look at the code much later. :)

>
>>> > - 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"... ;-)

Agreed. 

Roman: Even if the documentation you write is not 100% clear it will 
help out.  Then other people like Matthias and I can come along and 
refine and extend the documentation.

>
> 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?
>
Does epydoc auto-link between related classes?  If so, shouldn't we 
generate the reference documentation from both pygccxml and pyplusplus 
at the same time so we can follow links from pygccxml types used in 
pyplusplus?

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

You have pegged me correctly.  I am a native speaker.  I don't always 
speak it well, but I do speak it. :)

-Allen

>
> - Matthias -
>
>
>
> -------------------------------------------------------
> This SF.Net email is sponsored by xPML, a groundbreaking scripting 
> language
> that extends applications into web and mobile media. Attend the live 
> webcast
> and join the prime developer group breaking into this new coding 
> territory!
> http://sel.as-us.falkag.net/sel?cmd=lnk&kid=110944&bid=241720&dat=121642
> _______________________________________________
> pygccxml-development mailing list
> pyg...@li...
> https://lists.sourceforge.net/lists/listinfo/pygccxml-development
>