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]

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


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