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

[Frank Ch. Eigler]

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