Start of Systemtap Tapset Reference manual

[William Cohen]

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