This is the mail archive of the
systemtap@sourceware.org
mailing list for the systemtap project.
inline documentation syntax
- From: "Frank Ch. Eigler" <fche at redhat dot com>
- To: systemtap at sources dot redhat dot com
- Date: Tue, 5 Feb 2008 11:49:18 -0500
- Subject: inline documentation syntax
Hi -
A followup on my note regarding bug #5679. Other than nits regarding
my suggested operator "@@" (hey, pronounce it "look-here"!), the other
possibility would be to support javadoc. The difficulty with this is
that IMO it's important for the translator do directly parse this
stuff, and not just leave it to a separate documentation generator
tool.
One reason for that is because we want the impending "listing"
function (stap -l 'syscall.*') to produce informative data, such as:
syscall.read (syscalls.stp:55:33) - alias to kernel.function("sys_read")
fd - numeric file descriptor
buf_uaddr - user-space buffer pointer, use user_buffer()
count - number of bytes
argstr - formatted argument string
This same style of annotation and searching should also work for
functions and global variables.
One might imagine teaching the translator to parse javadoc and its
internal markup and then heuristically search for this info in /** */
comments left nearby the actual script code, but that idea leaves me
cold.
- FChE