This is the mail archive of the systemtap@sourceware.org mailing list for the systemtap project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]
Other format: [Raw text]

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


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]