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


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.



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