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: Start of Systemtap Tapset Reference manual


Randy Dunlap wrote:
William Cohen wrote:
I took a look to see how the kernel uses kernel-doc to extract the
information from the C files. I tried an experiment to see whether
kernel-doc could extract the comments out of a systemtap tapset file.
However, it appears that kernel-doc try to grock C syntax and looks for
a prototype for the function. Thus, it chokes on the following example:

/**
 * vm.pagefault - Records that a page fault occurred.
 * Context: The process which triggered the fault
 *
 *  @address: The address of the faulting memory access.
 *  @write_access: Indicates whether this was a write.
 */

kernel-doc also wants the @params: listed immediately after the function name/description (first) line. Then Context: or other info can be listed after the params, usually with an intervening "blank" (i.e., " *") line.

Thanks for the correction in the kernel-doc syntax.



kernel-doc is looking through the c code to try to extract additional information for enum/typedef/struct/function document comments. Would it

It's looking for explicit parameter types and return type since the @params comments & function name line don't include type info.

Ah the stuff that goes in the synopsis section of the output. I see now that some of the information is supplied by the C code itself.


be worthwhile to adapt kernel-doc so it can parse systemtap tapset
files? Is there some way to make kernel-doc only pay attention to the
comments?

Not currently, but I don't see why it couldn't be done. Then the question becomes: is it the same scripts/kernel-doc file or is it scripts/stap-doc (e.g. -- or some other name)?


kernel-doc ignores most of the file. The exception is the material right after the kernel-doc documentation comment. The keywords "function", "struct", "union", and "enum" control how kernel-doc looks for additional information in the source. For systemtap SystemTap would have additional parsing to probes and systemtap functions; have process_state_3_probe() and process_state3_sfunction() when the appropriate keyword is used to describe the documentation.


Also need to have dump_probe(), dump_sfunction() and the associated variations of output_(probe|sfunction)_(html|man|text|xml|gnome) to generate the appropriate output for the Systemtap probes and functions.

-Will


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