This is the mail archive of the
systemtap@sourceware.org
mailing list for the systemtap project.
Re: inline documentation syntax
- From: Martin Hunt <hunt at redhat dot com>
- To: "Frank Ch. Eigler" <fche at redhat dot com>
- Cc: systemtap at sources dot redhat dot com
- Date: Thu, 07 Feb 2008 11:36:14 -0500
- Subject: Re: inline documentation syntax
- Organization: Red Hat Inc.
- References: <20080205164918.GB8423@redhat.com>
On Tue, 2008-02-05 at 11:49 -0500, Frank Ch. Eigler wrote:
> Hi -
>
> 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. 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?
Personally, I hate long man pages. And doing something like "stap -l"
and piping that into an editor so I can search for some interesting
probe point does not appeal to me. 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.
>
> 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 and having it mixed in with full
documentation makes it confusing to parse. 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.