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

[David Smith <dsmith at redhat dot 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)