Re: [Discuss-gnuradio] gnuradio source patch to make it work with a current GCC 4.5.0

[Moeller]

 On 04.08.2010 19:24, Eric Blossom wrote:
> On Wed, Aug 04, 2010 at 05:35:01PM +0200, Moeller wrote:
>>  Oh sorry, thanks for the hint.
>> Apparently I only visited those source files without doxygen comments.
> FWIW, the doxygen comments are in the .h files
> Eric

>From the C sources I checked only a few examples.
Now, after digging more into the sources, I see lots of documented classes.
Anyway, I'm still missing the \file \brief doxygen tags
for the files. These are extremely useful when browsing through
a mass of unknown source material.
Otherwise you have to read the source in depth to find out what
the sourcefile is all about.
But most GNU projects only give the GPL legal information on top.

Python sources are less documented in gnuradio. For example
gnuradio-core\src\python\gnuradio\blks2impl\generic_usrp.py
No short info what this is all about. You have to read until line 130
to have an explanation about what a certain class is doing for "generic_usrp".
Is it a substitue for the usrp/usrp2 imports, an alternative way to access
USRP and USRP2? How to use it? I think most questions could be answered
with a few clear sentences for introduction.
For me, the gnuradio is less a hacking library, but more a solid basis
for student education, research and experimentation.
Like a substitute for Simulink for live radio purposes.

I know, if you're working a long time with a library, the structure is very 
clear.
But for beginners trying to understand the source, comments should be
more helpful. I would suggest to implement a short abstract to every source
file. Perhaps as a \file \brief header (I'm using these for every file),
in addition to the class based doc. What about extending
the docs/doxygen templates with more of the doxygen features?

Can the doxygen be extended to the Python part, too?
Doxygen is able to handle Python. I just don't know if the mix with
C-Source is possible. Perhaps it needs two independent doxygen
doc folders. For my own projects, I use Doxygen to generate a manual.
What about creating a readable Gnuradio manual in this way?
This is much more than just a class browser, with a lot of descriptions,
application examples, formulas for math functions, images, files overview.
It needs to introduce some doxygen text structure tags for this,
latex-includes, formulas, images, bibtex-literature list.

Moeller