Re: Start of Systemtap Tapset Reference manual

[William Cohen <wcohen at redhat dot com>]

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.
 */
probe vm.pagefault = kernel.function("__handle_mm_fault@mm/memory.c") ?,
                     kernel.function("handle_mm_fault@mm/memory.c") ?
{
	write_access = $write_access
	address =  $address
}

Giving the following error message:

Error(/home/wcohen/research/profiling/systemtap_write/systemtap_ref//tapset/memory.stp:19): 
cannot understand prototype: 'probe vm.pagefault = 
kernel.function("__handle_mm_fault@mm/memory.c") ?, 
kernel.function("handle_mm_fault@mm/memory.c") ? '

kernel-doc is looking through the c code to try to extract additional 
information for enum/typedef/struct/function document comments. Would it 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?

-Will