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
/* A collection of signal analysis functions. */
/*!
\file template.cpp
\date 2010-08-06
\author Mr. Gnuradio Developer, Dr. Me Too
\note these functions are very useful for finding unknown signals in noise
\sa based on math functions from the xyz package
\sa TFTB, time-frequency toolbox from octave
\warning the functions are not thread-safe in general
\warning according to the FCC rules, unauthorized listening to marsian signals is strictly forbidden
\bug segfaults, when compiled for cygwin posix environments
\todo higher order statistics are missing, should be included soon
\brief A collection of signal analysis functions.
These are the building blocks for the "signal analyzer" program module
of the Gnuradio "RadioMonitor" Application.
Many algorithms are inspired by the Octave Time Frequency Toolbox TFTB,
but also additional algorithms were collected for this great library.
Brief description ends at paragraph border.
A very detailed description here.
Sophisticated mathematical tranformations allow a better insight into radio signals.
This library is an approach to collect all relevant signal analysis functions,
from time frequency distributions over higher order statistical algorithms
to AI signal understanding modules based on neural networks.
Of course we are only kidding, because this library does not really exist.
This is only a template for heros that want to implement all this.
Listing the basic properties
- list item 1
- subitem
- sub sub
- sub sub 2, a dot will end this sub sub
.
.
- list item 2
.
Further information, see this website
<a href="http://linkURL";>further reading</a>
Using a <tt>typewriter font</tt> here.
A small inline formula here \f$(x_1,y_1)\f$, nice in LaTeX.
A display-style formula to describe the mathematical background of this model:
\f[
|I_2|=\left| \int_{0}^T \psi(t)
\left\{
u(a,t)-
\int_{\gamma(t)}^a
\frac{d\theta}{k(\theta,t)}
\int_{a}^\theta c(\xi)u_t(\xi,t)\,d\xi
\right\} dt
\right|
\f]
This is a block diagram of the architecture:
\image html block_diagram_raster.png "Architecture of xyz"
\image latex block_diagram_vectorgraphics.pdf "Architecture of xyz" width=10cm
The PDF manual will get a better vector graphics with super fine contours in publishing quality.
\latexonly
This text is for the gnuradio PDF manual. Latex will produce a nice layout.
And you can cite very important sources \cite[Page 99]{Proakis2000} here.
\endlatexonly
*/
... lots of source code
think about it in the most general form
gnuradio is working on some hardware
that has attached a
- list of radio devices (including audio device)
variable length, containing handlers (pointer to device objects), describing
strings etc.
- a device can group some subdevices
- every device and subdevice has capabilities, properties and settings
some are obligatory :
- device type, string 'audio','usrp1','usrp2','anothersdr','customdevice'
- device serial number (unique)
capabilities
- returns frequency range for centerfrequency
- maximum bandwith, samplerate, ...
settings
some are not used for all devices, but comparable parameters are using
standarized keywords
- center frequency (obligatory for usrp, but not available for audio device)
- lo frequency
- decimation factor
- gain
- filter settings
- special preselector filter settings (controlling real hardware)
very important:
at compile-time, the variety of devices should not be restricted, so
- use flexible and dynamic data structures,
like std::map key-value listings
- dynamic data types where necessary (e.g. boost::variant or boost::any)
/* one line description */
/*!
\file template.cpp
\date 2010-08-06
\author
\note
\sa
\warning
\bug
\todo
\brief
Detailed
*/
_______________________________________________
Discuss-gnuradio mailing list
Discuss-gnuradio@gnu.org
http://lists.gnu.org/mailman/listinfo/discuss-gnuradio
