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
Hi -
dsmith wrote:
> [...]
> > Yeah, it's a bit odd, but consider the alternatives: separately
> > written man pages and/or javadoc-style comment markup.
> [...]
> Why couldn't the probe's documentation string list the available
> variables? Taking the example from above:
>
> probe ioscheduler.elv_next_request
> = kernel.function("elv_next_request")
> @@ "Probe the retrieval of a I/O request from request queue."
> @@ "Provides:"
> @@ " elevator_name: the elevator name"
> {
> elevator_name =
> %( kernel_v >= "2.6.10" %?
> kernel_string($q->elevator->elevator_type->elevator_name) %:
> kernel_string($q->elevator->elevator_name) %)
> }
Perhaps. One problem here is that then it's heard to create a
non-verbose listing (just to show the probe "headline"), or else the
text would be structured and would have to be internally parsed.
Another problem: it duplicates and/or makes it harder to mechanically
enforce "documentation coverage".
- FChE