[Discuss-gnuradio] Re: documentation of the gnuradio python modules

[Markus Feldmann]

Martin Braun schrieb:
> On Mon, Mar 23, 2009 at 12:42:04PM +0000, feldmaus wrote:
> > Hi All,
> >
> > i only want to say,it would be nice to have a clearer and
> > more comprehensive gnuradio python modules documentation with
> > examples.
> >
> > This would solve many basic problems !
>
> Hi Markus,
>
> as explained in
> http://gnuradio.org/trac/wiki/Tutorials/WritePythonApplications, the
> Doxygen generated docs are also very useful for Python development,
Ok for python development, but not for using python.
> since the functions which export the blocks to the Python domain are
> always mapped in the same way (e.g. gr_make_sig_source_f becomes
> gr.sig_source_f etc.). I always have a browser window open with my local
> copy of the Doxygen files when developing GR and I find it very easy to
> jump straight to the correct block documentation thanks to the
> categories of signal processing blocks.
> The only disadvantage I see is that default arguments don't show up in
> the doxy-docs - but as the source code is always linked into the
> documentation, this is very easy to find if necessary.
>
> I admit this might be a bit cumbersome for people who don't want to
> touch the C++ domain at all, but for someone who at least knows how to
> read the code it doesn't take much getting used to.
>
> As for examples, between the unit tests and the files in
> gnuradio-examples and gr-utils, there really is loads of stuff to choose
> from regarding examples. grep and find are your friends.
>
> I'm sorry that this answer doesn't exactly give you what you asked for -
> but even though I agree that documentation is not GNU Radio's strongest
> point, I must say the way the code is organised makes it extremely easy
> to find oneself's way around without too much of a hassle. Just give it
> a try, I doubt you'll find it that hard yourself.
>
> Cheers
> MB
Hi Martin and thanks for your answer,

I am an user not developer, so i am not reading C++ code
to understand how this function works. C++ code is not
equal documentation. And there is also a need for long
discriptions. You are using the API like a reference book.
A reference book is useful, but not for beginners.

A beginner doesn't know which possibilities are there to solve
a specific problem ! Where in the API is written which
solutions exists to get an offset in the amplitude ? (for example)
Ok a beginner could read the whole API first and than
maybe he knows it. There is still a difference between "i know there
is a function which could be useful" and the "knowledge to use this
method correctly".

The examples are very useful, but it should be more explained
step by step. The API could be more useful, if all parameters are
explained. The API doesn't give me any answer how to solve my
problem, but give me infos about the paramter type i can load
into some method and the return type.
It is nice that there is a short explanation of some methods,
but for difficult methods it should be more explained.

Regards Markus