Re: [Bug translator/5679] inline documentation for scripts/tapsets

[David Smith <dsmith at redhat dot com>]

Frank Ch. Eigler wrote:
> Hi -
> 
> dsmith wrote:
>> [...]
>>> 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.  
> 
> Yeah, it's a bit odd, but consider the alternatives: separately
> written man pages and/or javadoc-style comment markup.

...

>> When would you see a user needing the documentation for
>> 'elevator_name'?
> 
> When she finds a probe on the topic of i/o schedulers, she'll want to
> know which variables the alias makes available, so that she doesn't
> have to use $expressions.

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) %)
}

-- 
David Smith
dsmith@redhat.com
Red Hat
http://www.redhat.com
256.217.0141 (direct)
256.837.0057 (fax)