SystemTap Tapset Reference Manual

SystemTap Tapset Reference Manual

[William Cohen]

Recently I included a tweaked version of kernel-doc from the linux kernel in 
systemtap to extract documentation from the tapsets and produce html, pdf, and 
man pages. A number of the tapset files were modified to include the extractable 
documentation information (for example  socket.stp and context.stp)

When systemtap is configured a directory doc/SystemTap_Reference_Manual is setup 
with a makefile. This make file will generate the html pdf and man pages in 
subdirectories. Currently this makefile isn't connected to the top-level 
makefile and it doesn't install the resulting documentation. However, it should 
be relatively simple to add those.

If people familar with specific tapsets to got through and review and/or add the 
documentation comments to tapsets, that would be greatly appreciated. For 
sytemtap probes the structure is the following:

/**
  * probe probe_name(:)? (- short description)?
(* @variable(space)*: (description of probe variable x)?)*
(* a blank line)?
  * (Description:)? (Description of probe)?
  * (section header: (section description)? )*
(*)?*/

For systemtap functions it is:

/**
  * sfunction function_name(:)? (- short description)?
(* @parameter(space)*: (description of function parameter x)?)*
(* a blank line)?
  * (Description:)? (Description of function)?
  * (section header: (section description)? )*
(*)?*/

-Will

Re: SystemTap Tapset Reference Manual

[K.Prasad]

On Fri, Dec 05, 2008 at 12:27:52PM -0500, William Cohen wrote:
> Recently I included a tweaked version of kernel-doc from the linux kernel 
> in systemtap to extract documentation from the tapsets and produce html, 
> pdf, and man pages. A number of the tapset files were modified to include 
> the extractable documentation information (for example  socket.stp and 
> context.stp)
>
> When systemtap is configured a directory doc/SystemTap_Reference_Manual 
> is setup with a makefile. This make file will generate the html pdf and 
> man pages in subdirectories. Currently this makefile isn't connected to 
> the top-level makefile and it doesn't install the resulting 
> documentation. However, it should be relatively simple to add those.
>
> If people familar with specific tapsets to got through and review and/or 
> add the documentation comments to tapsets, that would be greatly 
> appreciated. For sytemtap probes the structure is the following:
>
> /**
>  * probe probe_name(:)? (- short description)?
> (* @variable(space)*: (description of probe variable x)?)*
> (* a blank line)?
>  * (Description:)? (Description of probe)?
>  * (section header: (section description)? )*
> (*)?*/
>
> For systemtap functions it is:
>
> /**
>  * sfunction function_name(:)? (- short description)?
> (* @parameter(space)*: (description of function parameter x)?)*
> (* a blank line)?
>  * (Description:)? (Description of function)?
>  * (section header: (section description)? )*
> (*)?*/
>
> -Will

I think this should be documented in the SystemTap website, perhaps
under the "Tapset Developer's Guide" -
http://sources.redhat.com/git/?p=systemtap.git;a=blob_plain;f=tapset/DEVGUIDE.

I'm assuming that this style is going to be the de-factor standard for
documentation, deprecating the man-page creation process described in
the link above. If so, can you update the "Documentation" section in the
above file with the process you've described in the previous mail?

Thanks,
K.Prasad

Re: SystemTap Tapset Reference Manual

[William Cohen]

K.Prasad wrote:

> I think this should be documented in the SystemTap website, perhaps
> under the "Tapset Developer's Guide" -
> http://sources.redhat.com/git/?p=systemtap.git;a=blob_plain;f=tapset/DEVGUIDE.
> 
> I'm assuming that this style is going to be the de-factor standard for
> documentation, deprecating the man-page creation process described in
> the link above. If so, can you update the "Documentation" section in the
> above file with the process you've described in the previous mail?
> 
> Thanks,
> K.Prasad
> 

Hi Prasad,

Thanks for the suggestion. I have revised the "Documentation" section of
DEVGUIDE to describe the new documentation process.

-Will