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:
> [...]
> > 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.
> 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).
Yes, but emacs is different in this regard. Here, the variables
provided by aliases are first class interfaces being provided to
end-user scripts.
> 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.
> How would he get it?
Oh, it's a "he" now? Oh well, that happens too. He could get
it with a verbose listing, a la:
% stap -lv 'ioschedule.el*'
> Why is this documentation better than just a comment?
It's not a huge difference, but it could reduce the necessity for
someone to pop open a tapset script.
> 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?
Documentation strings are not propagated into the generated code, so
yeah, they should merge the same way with the existing algorithms.
- FChE