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

[John Gilmore]

I like your ideas!

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

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]
==> call-cmds.h <==
/* ***DEPRECATED***  The gdblib files must not be calling/using things in any

==> c-exp.c <==
/* A Bison parser, made by GNU Bison 1.875c.  */

==> charset.c <==
/* Character set conversion support for GDB.

==> charset.h <==
/* Character set conversion support for GDB.

==> c-lang.c <==
/* C language support routines for GDB, the GNU debugger.

==> c-lang.h <==
/* C language support definitions for GDB, the GNU debugger.

==> cli-out.c <==
/* Output generating routines for GDB CLI.

==> cli-out.h <==
/* Output generating routines for GDB CLI.

==> coff-pe-read.c <==
/* Read the export table symbols from a portable executable and

==> coff-pe-read.h <==
/* Interface to coff-pe-read.c (portable-executable-specific symbol reader).

==> coffread.c <==
/* Read coff symbol tables and convert to internal format, for GDB.

==> command.h <==
/* Header file for command-reading library command.c.

==> complaints.c <==
/* Support for complaint handling during symbol reading in GDB.

==> complaints.h <==
/* Definitions for complaint handling during symbol reading in GDB.

==> completer.c <==
/* Line completion stuff for GDB, the GNU debugger.

==> completer.h <==
/* Header for GDB line completion.

==> copying.c <==
/* ==> Do not modify this file!!  It is created automatically

==> corefile.c <==
/* Core dump and executable file functions above target vector, for GDB.

==> corelow.c <==
/* Core dump and executable file functions below target vector, for GDB.

==> core-regset.c <==
/* Machine independent GDB support for core files on systems using "regsets".

==> cp-abi.c <==
/* Generic code for supporting multiple C++ ABI's

==> cp-abi.h <==
/* Abstraction of various C++ ABI's we support, and the info we need

==> cp-name-parser.c <==
/* A Bison parser, made by GNU Bison 1.875c.  */

==> cp-namespace.c <==
/* Helper routines for C++ support in GDB.

==> cp-support.c <==
/* Helper routines for C++ support in GDB.

==> cp-support.h <==
/* Helper routines for C++ support in GDB.

==> cp-valprint.c <==
/* Support for printing C++ values for GDB, the GNU debugger.

==> cris-tdep.c <==
/* Target dependent code for CRIS, for GDB, the GNU debugger.

==> c-typeprint.c <==
/* Support for printing C and C++ types for GDB, the GNU debugger.

==> c-valprint.c <==
/* Support for printing C values for GDB, the GNU debugger.

% head -15 c-valprint.c
/* Support for printing C values for GDB, the GNU debugger.

   Copyright (C) 1986, 1988, 1989, 1991, 1992, 1993, 1994, 1995, 1996, 1997,
   1998, 1999, 2000, 2001, 2003, 2005, 2006, 2007, 2008
   Free Software Foundation, Inc.

   This file is part of GDB.

   This program is free software; you can redistribute it and/or modify
   it under the terms of the GNU General Public License as published by
   the Free Software Foundation; either version 3 of the License, or
   (at your option) any later version.

   This program is distributed in the hope that it will be useful,
   but WITHOUT ANY WARRANTY; without even the implied warranty of
[...]

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.

> For me, the gnuradio is less a hacking library, but more a solid basis
> for student education, research and experimentation.

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.

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

        John