added commenting/documentation guidelines

1 files changed, 174 insertions, 7 deletions

diff --git a/doc/Tapset_Reference_Guide/en-US/Tapset_Dev_Guide.xml b/doc/Tapset_Reference_Guide/en-US/Tapset_Dev_Guide.xml
index 26ea9896..555fa7e6 100644
--- a/doc/Tapset_Reference_Guide/en-US/Tapset_Dev_Guide.xml
+++ b/doc/Tapset_Reference_Guide/en-US/Tapset_Dev_Guide.xml
@@ -99,19 +99,186 @@ kernel.function("compat_do_execve")
 	that the process ID of the new process is retrieved by calling 
 	<command>task_pid()</command> and passing it the <command>task_struct</command>
 	pointer. In this case, the auxiliary function is an embedded C function
-	that's defined in the task tapset (<filename>task.stp</filename>).
+	defined in <filename>task.stp</filename>.
+</para>
+
+<programlisting>
+probe process.create = kernel.function("copy_process").return 
+{
+   task = $return
+   new_pid = task_pid(task)
+}
+</programlisting>
+
+<para>
+	It is not advisable to write probes for every function. Most SystemTap users
+	will not need or understand them. Keep your tapsets simple and high-level.
 </para>
 
 <remark>info from here:http://sources.redhat.com/git/?p=systemtap.git;a=blob_plain;f=tapset/DEVGUIDE</remark>
 
 	</section>
+	
+<section id="Tapsetelements">
+	<title>Elements of a Tapset</title>
+		
+	<para>
+		The following sections describe the most important aspects of writing a tapset. Most of
+		the content herein is suitable for developers who wish to contribute to 
+		SystemTap's upstream library of tapsets.
+	</para>
+	
+<section id="Tapsetelements-tapsetfiles">
+	<title>Tapset Files</title>
+	
+	<para>
+		Tapset files are stored in <filename><replaceable>src</replaceable>/tapset/</filename> 
+		of the SystemTap GIT directory. Most tapset files are kept at that level. If you have
+		code that only works with a specific architecture or kernel version, you may 
+		choose to put your tapset in the appropriate subdirectory.
+	</para>
+	
+	<para>
+		Installed tapsets are located in <filename>/usr/share/systemtap/tapset/</filename>
+		or <filename>/usr/local/share/systemtap/tapset</filename>.
+	</para>
+	
+	<para>
+		Personal tapsets can be stored anywhere. However, to ensure that SystemTap
+		can use them, use <command>-I <replaceable>tapset_directory</replaceable></command> 
+		to specify their location when invoking <command>stap</command>.
+	</para>
+</section>	
+	
+<section id="Tapsetelements-namespace">
+	<title>Namespace</title>
+	
+	
+	<para>
+		Probe alias names should take the form
+		<command><replaceable>tapset_name.probe_name</replaceable></command>.
+		For example, the probe for sending a signal could be named 
+		<command>signal.send</command>.
+	</para>
+	
+	<para>
+		Global symbol names (probes, functions, and variables) should be unique
+		accross all tapsets. This helps avoid namespace collisions in scripts
+		that use multiple tapsets. To ensure this, use tapset-specific 
+		prefixes in your global symbols.
+	</para>
+	
+	<para>
+		Internal symbol names should be prefixed with an underscore 
+		(<command>_</command>).
+	</para>
+</section>	
+
+<section id="Tapsetelements-docscomments">
+	<title>Comments and Documentation</title>
+	
+	<para>
+		All probes and functions should include comment blocks that describe
+		their purpose, the data they provide, and the context in which they run 
+		(e.g. interrupt, process, etc). Use comments in areas where your intent may not
+		be clear from reading the code. 
+	</para>
+	
+	<para>
+		Note that specially-formatted comments are automatically extracted from most 
+		tapsets and included in this guide. This helps ensure that tapset contributors
+		can write their tapset <emphasis>and</emphasis> document it in the same place.
+		The specified format for documenting tapsets is as follows:
+	</para>
+	
+<programlisting>
+/**
+ * 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".
+ **/
+</programlisting>
+	
+<para>For example:</para>
+
+<programlisting>
+/**
+ * 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>.
+ **/
+</programlisting>
+
+<para>To override the automatically-generated <command>Synopsis</command> content, use:
+	
+<programlisting>
+ * Synopsis:
+ * <programlisting>Synopsis string</programlisting>
+ *
+</programlisting>
+
+<para>For example:</para>
+
+<programlisting>
+/**
+ * probe signal.handle - Fires when the signal handler is invoked
+ * @sig: The signal number that invoked the signal handler
+ *
+ * Synopsis:
+ * &lt;programlisting>static int handle_signal(unsigned long sig, siginfo_t *info, struct k_sigaction *ka,
+ * sigset_t *oldset, struct pt_regs * regs)&lt;/programlisting>
+ */
+</programlisting>
+
+<para>
+	It is recommended that you use the <command>&lt;programlisting&gt;</command> tag in 
+	this instance, since overriding the <command>Synopsis</command> content of an entry
+	does not automatically form the necessary tags.
+</para>
+
+<para>
+	For the purposes of improving the DocBook XML output of your comments, you can also
+	use the following XML tags in your comments:
+</para>
+
+<itemizedlist>
+	<listitem><para><command>command</command></para></listitem>
+	<listitem><para><command>emphasis</command></para></listitem>
+	<listitem><para><command>programlisting</command></para></listitem>
+	<listitem><para><command>remark</command> (tagged strings will appear in Publican beta
+			builds of the document.</para></listitem>
+</itemizedlist>
+
+
+</section>
+	
+</section>	
+	
 <!--	
-	<section id="Tapset_Reference_Guide-Test-Section_2_Test">
-		<title>Section 2 Test</title>
-		<para>
-			Test of a section
-		</para>
-	</section>
+<section id="Tapset_Reference_Guide-Test-Section_2_Test">
+	<title>Section 2 Test</title>
+	<para>
+		Test of a section
+	</para>
+</section>
 -->
 </chapter>