This is the mail archive of the
systemtap@sourceware.org
mailing list for the systemtap project.
Re: SystemTap Tapset Reference Manual
- From: "K.Prasad" <prasad at linux dot vnet dot ibm dot com>
- To: William Cohen <wcohen at redhat dot com>
- Cc: SystemTAP <systemtap at sources dot redhat dot com>
- Date: Wed, 4 Feb 2009 00:32:46 +0530
- Subject: Re: SystemTap Tapset Reference Manual
- References: <49396498.1010700@redhat.com>
- Reply-to: prasad at linux dot vnet dot ibm dot com
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