This is the mail archive of the
systemtap@sourceware.org
mailing list for the systemtap project.
Re: inline documentation syntax
Hi -
On Thu, Feb 07, 2008 at 11:36:14AM -0500, Martin Hunt wrote:
> > A followup on my note regarding bug #5679. Other than nits regarding
> > my suggested operator "@@" (hey, pronounce it "look-here"!), the other
> > possibility would be to support javadoc. The difficulty with this is
> > that IMO it's important for the translator do directly parse this
> > stuff, and not just leave it to a separate documentation generator
> > tool.
>
> It would be nice to hear why you think that is. This idea is fine at
> some level, but I don't understand what the big picture is.
I gave some information about this in that selfsame message, but it is
admittedly fuzzy.
> How does a systemtap script writer find our what tapsets are
> available, choose the correct one, then find out which probes in
> that tapset are useful?
BTW, a systemtap script writer does not choose a tapset, as tapset
files are largely an implementation detail. She may look up probes /
functions / variables. She may search for topics and keywords, but
without a lot more metadata, we can't help beyond apropos(1).
> Personally, I hate long man pages. [...]
Well, one has to choose one's poison. It's also awful to have
hundreds of tiny man pages, each a screen long but with just a few
lines of useful content.
> We also need proper documentation, indexed, searchable, with
> information presented in a high-level of detail. Doing that will
> mean more verbose information after those @@s, adding new syntax
> things like "see also", links, embedded information, etc.
>
> Soon you will have duplicated doxygen inside stap.
That would be a poor outcome. On the bright side, we would stop well
short of Doxygen, which I've not yet been able to get to generate
*concise* data - perhaps even more compact than the stapprobes.FOO.5
files currently. Would you give it a try? I'm not looking for HTML
eyecandy.
I'm fond of the idea of systemtap-processed documentation for another
reason: to enable mechanical enforcement of guidelines to document
things. A separate tool would not have the semantic knowhow to help
us find obsolete or missing text. I find more inspiration in elisp
than perldoc, javadoc, or doxygen.
> > One reason for that is because we want the impending "listing"
> > function (stap -l 'syscall.*') to produce informative data, such as:
> >
> > syscall.read (syscalls.stp:55:33) - alias to kernel.function("sys_read")
> > fd - numeric file descriptor
> > buf_uaddr - user-space buffer pointer, use user_buffer()
> > count - number of bytes
> > argstr - formatted argument string
>
> I think I'd rather see "stap -l" print a list of matching probes. That's
> useful information by itself [...]
Good point. (We will also want matching functions and variables.)
> [...] Maybe then "stap -ll" would give full documentation. Possibly
> by passing the probe name to a script that simply fetched the
> information from some previously generated documentation or doc
> tool.
That could work. However, it reminds me of one more reason for
translator-side documentation: that some of it can be
machine-generated.
For example, for aliases that map to kprobes and/or markers, systemtap
can tell the user exactly which low-level probe points result from a
pattern, at which addresses, in which modules/processes, etc. Or it
could add analytical data like number of statements, loops, variable
locking/contention, all to give an indication of the cost of the
probe. Those are all functions of the current machine state and
cannot be pulled from build-time text files.
- FChE