TAPSET REFERENCE GUIDE: DOCUMENTATION PLAN

This is the project page for the !Tapset Reference Guide project. It contains high-level information regarding each phase of The Publication Lifecycle, used by Engineering Content Services as a documentation project template.

PURPOSE

While tapsets are useful in providing functions for instrumenting the Linux kernel, they are only helpful as long as users are aware of them.

The SystemTap team has developed a process through which proper documentation can be extracted from source comments into XML. This way, tapset contributors can submit their code *and* the proper documentation for it in the same place, all without having to go through XML, Troff, SGML, or other form of special mark-up. The extraction process takes care of providing the proper markup.

This project's immediate goals are as follows:

Document all available tapsets in code comments.

Improve the existing "comment extraction" system as well as possible, to ensure that the generated source is compatible with both kernel-doc and Publican.

The long-term goal of this project is to provide a framework for tapset documentation that is easy for tapset contributors to follow. This should help ensure that tapset documentation grows alongside the tapset library.

PROCESS

All actual content generation and revision should occur exclusively in these tapset files (except for static content -- e.g. Introduction, Legal Notices, Preface, etc). This ensures that a specific tapset and its documentation both appear in the same area, making it easier for both items to maintain (and keep in sync).

To view git commit messages related to this project, refer to the following link.

DOCUMENTING A TAPSET

To document a tapset, add a comment above the tapset code in the corresponding tapset script using the following format:

/**
* probe tapset.name - Short summary of what the tapset does.
* @argument: Explanation of argument.
* @argument2: Explanation of argument2. Probes can have multiple arguments.
*
* Context:
* A brief explanation of the tapset context. Note that the context should only be 1 paragraph short.
*
* Text that will appear under "Description."
*
* A new paragraph that will also appear under the heading "Description".
*
* Header:
* A paragraph that will appear under the heading "Header".
**/

For example:

/**
* probe vm.write_shared_copy- Page copy for shared page write.
* @address: The address of the shared write.
* @zero: Boolean indicating whether it is a zero page
* (can do a clear instead of a copy).
*
* Context:
* The process attempting the write.
*
* Fires when a write to a shared page requires a page copy. This is
* always preceded by a <command>vm.shared_write</command>.
*/