Re: [Discuss-gnuradio] Brief tags describing each source file

[Moeller]

 On 06.08.2010 00:30, John Gilmore wrote:
> When I was maintaining GDB, I found it very handy to put a one-line
> comment at the top of each file, like this:
>
> % head -1 c*.[ch]
> ==> c-exp.c <==
> /* A Bison parser, made by GNU Bison 1.875c.  */
This is not a replacement for a comprehensive doxygen-header,
but I like this idea of a short one-liner fixed on line "1".
So, it's really easy to parse with the head command.
Parsing doxygen comments would be harder, because you have
to detect the context (does \brief belong to a file header or to a class).

I think this is not redundant to the \file \brief doxygen short abstract, so
in the end you could have abstract at 3 detail levels: one-liner on top,
a \brief doxygen description in a few lines, and (optionally) a more
detailed description. Not bad when browsing the source.

The \brief doxygen statements are also very nice for generating a
software manual from the source and additional LaTex text files.

> I suspect that if you, Moeller, submitted a patch that added
> a similar comment to every GNU Radio source file that you understand
> the function of, it would be accepted.  And might even inspire others
> who understand different files to add their own insights.  And some
> maintainer or volunteer might someday complete the task for all the
> files, and revise the coding standards to require it on new files.
Unfortunatly, my spare time is nearly zero. I'm just looking for a solid basis
for experiments in our laboratory. Gnuradio is a good choice.
Possibly, later we could publish a few contributions to Gnuradio out of this 
work.

I attached my idea of a source file template. I'm using a similar header for all
of my source files. Organization into files give the software a certain 
structure,
so I like the file-based documentation. Additionally I write short comments to 
the
classes and functions, too.

It would be useful, to place such a source file template somewhere between
the gnuradio-examples programs. The c++/dial_tone examples are not documented
at all. The examples in docs/docygen only carry a class based doxygen header.
This is Ok, if there is only one class per file. But for multiple classes, I 
would
add a file-based header.

> The great thing about free software is that one guy can push it
> in a direction they choose, like becoming a better educational tool.
> All it takes is time, work, and some coordination.
I think a handbook for gnuradio is missing.
Students trying to understand gnuradio have no long programming experience,
and usually no Python experience. They might be frustrated, if it's too hard
to understand the library, all the files, includes, classes and different 
approaches
(like using separate sources for different device types).
There is not much time for it between exams.

For my own projects I use doxygen to generate software manuals.
One thing is the automatic class documentation, derived from the C++ data
structures and doxygen-tag comments.
Another very important part is the additional text you write for this manual.
I'm using doxygen- and latex-includes to add a title page, introduction, some 
chapters,
formulas, screenshots etc.
It will produce a nice PDF document in the end, with TOC, bibliography, index.
I'm not familiar with a HTML variant of this. But it should be possible.
There are some \latexonly and \htmlonly statements in doxygen.
So this could be differentiated somehow.

>> In rx_timed_samples.cpp
>> the URSP-device is hard-wired, as a uhd-derived class.
>> "uhd::usrp::simple_usrp::sptr sdev"
>> So, once compiled, it can only support the USRP-type.
>>
>> I would prefer to leave this dynamic.
> I agree, and have been concerned about this aspect of GNU Radio
> for years.  Moeller, do you have a design for how it should work?
> If the community doesn't hate your design, are you willing to
> implement it?

In the attached txt, I wrote down some thoughts about it.
It seems that UHD has the same direction.
For me it's important that dynamic data structures are used.
So, e.g. a std::map key-value list of device properties.
At compile-time, all can be left dynamic. If a device does not
provide a certain capability, the property values are simply not allocated.
If a sample program wants this value, it should handle the case that it
does not exist (e.g. no centerfrequency for an audio device).
In contrast, the standard C++ way would be to derive a device-specific
class from a generic abstract class.
This problem is, that this is not flexible during run-time.
And every device-type would need a special source file.
I didn't understand exactly, how UHD would handle this.

Moeller

template_example.cpp
Description: Text Data

universal device.txt
Description: Text document

template.cpp
Description: Text Data