This is the mail archive of the systemtap@sourceware.org mailing list for the systemtap project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]
Other format: [Raw text]

Re: SystemTap Tapset Reference Manual


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


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]