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


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