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: [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


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