Re: [pygccxml-development] Updated status

[Roman Y. <rom...@gm...>]

On 3/7/06, Matthias Baas <ba...@ir...> wrote:
> > 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).

Because it is very difficult to find something, also it does not makes
code to look better :-)

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

I don't see alternative, :-(

> >> > - Comments: We *really* need comments and documentation for the clas=
ses
> >> > and methods in pygccxml and pyplusplus.  I think Matthias and I coul=
d
> >> > help out by pointing to areas of the code and saying in our very nic=
est
> >> > 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, ple=
ase :-)
>
> 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)?

Yes of course.

> 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 will take it as a rule

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

Yes, please go ahead.

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

After first release of pyplusplus I definitely propose to talk a
little about our self :-).

When I was young, I did not think that this could be possible. I was
born in Soviet Union,
Ukraine. I think this is great.

> - Matthias -

Roman

--
Roman Yakovenko
C++ Python language binding
http://www.language-binding.net/