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] |
Hi - > [...] > > How would you justify much effort on runtime documentation? > > Because people other than you use it and have questions. Are these questions of the sort that more doxygen markup would necessarily preempt? Direct use of the runtime outside systemtap is unlikely to become a priority. > It is used in tapsets. I foresee this being the case less and less. In particular, other than a small group of existing routines are given a script-side handler > Porting the arch-dependent pieces and testing it is necessary for > supporting new cpus. OK. Depending on the scale of code involved, one might use ordinary comments or file groupings to highlight portworthy areas. > > There is not a substantial difference. A script in .../tapset can > > contain any mixture of global/probe/probe-alias/function definitions, > > and may satisfy and generate external references with respect to other > > scripts. The translator attempts to automatically resolve all these > > kinds of references. > > From an implementation standpoint, there is no difference. From a script > developer's standpoint, there is a huge difference. We need to collect > utility functions, that basically extend the language, group them > together and document them well. That way all scripts and tapsets can > make use of them. Your formulation misses my point. By virtue of the automatic resolution logic in the translator, *all* scripts provide new "builtins" or "utilities", whether they be global variables, probe point aliases, or functions. All tapset scripts need to be written to enable and exploit the same kind of reuse. > > > We need some standard for documenting tapset functions. > > > > Like stapfuncs(5), stapprobes(5), and future stapvars(5)? Maybe > > slicing the same content up "horizontally" (by tapset rather than by > > exported artifact category) would also make sense, and maybe this can > > be accomplished by mechanical means. > > When we have a few dozen tapsets, I think you will not enjoy paging > through enormous man pages. Each tapset needs to be documented > individually and the tapset documentation automatically merged by some > means. That is what I meant by slicing it up horizontally. Which form ends up being written by hand vs. machine doesn't make much difference. > And it needs to be easily searchable and indexed. [...] What more than (say) apropos(1) do you envision for this? - FChE
Attachment:
pgp00000.pgp
Description: PGP signature
Index Nav: | [Date Index] [Subject Index] [Author Index] [Thread Index] | |
---|---|---|
Message Nav: | [Date Prev] [Date Next] | [Thread Prev] [Thread Next] |