tapset quality

["Frank Ch. Eigler" <fche at redhat dot com>]

Hi -

I am concerned that the quality of our tapsets is failing to improve,
and in some cases we regress in terms of documentation and testing
coverage.  This cannot continue.

There have been suggestions of formal code reviews on the mailing list
to help improve the situation.  Perhaps it is time to consider this
idea more seriously.  Perhaps it is simly a matter of reminding people
to please reread and follow the guidelines in src/HACKING and
src/tapset/DEVGUIDE.


There are some *technical* means we can take to help the situation.
Please share your ideas too.

Will Cohen's script coverage code in the translator lets one identify
which parts of the tapset are not even compiled.  We need someone to
bootstrap an ongoing process to take this data and create some buildok
tests for as many of them as possible.  Any volunteers, please?  If
the coverage generator is fast enough now to keep it on, I'll change
the test suite to report on its own coverage at the conclusion of a
test run.

Automatically extracted documentation has come up a few times, and
Mike Mason kindly prototyped this a few months ago.  I promised to
make an alternative proposal, so here it is.  Instead of using an
external tool to process script source files, how about extending the
translator to consume documentation strings - like emacs-lisp?  We
could extend the grammar to accept string literals in a few more
places.  How about:

probe foo "DESCRIPTION-STRING"
          "MORE-BLAH" {
  var "DESCRIPTION" = EXPR
}
function bar "DESCRIPTION" (var:long "DESCRIPTION" , ...) { }
global baz "DESCRIPTION"

The translator would associate the description strings with the
objects (probes/functions/variables).  It could synthesize additional
ones for e.g. dwarf probes, to provide metadata such as PC addresses,
probe alias chains.  Most importantly, with a new option or two, the
translator could spit out the documentation in an organized fashion
(on the command line, kind of like dtrace -l but better; as man pages
for installation).

- FChE