Re: Start of Systemtap Tapset Reference manual

[Randy Dunlap <randy.dunlap@oracle.com>]

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.


> 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

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

> 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)?

-- 
~Randy