This is the mail archive of the
systemtap@sourceware.org
mailing list for the systemtap project.
Re: [Bug translator/5679] inline documentation for scripts/tapsets
- From: David Smith <dsmith at redhat dot com>
- To: "Frank Ch. Eigler" <fche at redhat dot com>
- Cc: systemtap at sources dot redhat dot com
- Date: Mon, 11 Feb 2008 11:36:33 -0600
- Subject: Re: [Bug translator/5679] inline documentation for scripts/tapsets
- References: <20080126023636.5679.fche@redhat.com> <20080208232658.17393.qmail@sourceware.org> <20080209000424.GE24083@redhat.com>
Frank Ch. Eigler wrote:
> By the way, here are some excerpts from what a converted tapset may
> look like. It combines information currently in the man pages and in
> previous comment blocks, so is best compared to a union of the tapset
> source code AND the man page.
>
>
> ----------------------------------------
> // IO scheduler tapset
> // [...]
> probe ioscheduler.elv_next_request
> = kernel.function("elv_next_request")
> @@ "Probe the retrieval of a I/O request from request queue."
> {
> elevator_name =
> %( kernel_v >= "2.6.10" %?
> kernel_string($q->elevator->elevator_type->elevator_name) %:
> kernel_string($q->elevator->elevator_name) %)
> @@ "The elevator name."
> }
Hmm. That looks a bit intrusive to me, at least on a first glance,
especially for the variable documentation. I believe you mentioned that
you had found some inspiration in emacs lisp's documentation feature.
In emacs, you only document the function itself, not variables within it
(as far as I can remember).
When would you see a user needing the documentation for 'elevator_name'?
How would he get it? Why is this documentation better than just a
comment?
An unrelated question - we currently merge two probes that have the same
body. If we had 2 probes that were the same, except for their
documentation, are they still identical?
--
David Smith
dsmith@redhat.com
Red Hat
http://www.redhat.com
256.217.0141 (direct)
256.837.0057 (fax)