cleanup for documentation

1 files changed, 31 insertions, 28 deletions

diff --git a/tapset/memory.stp b/tapset/memory.stp
index ea976d15..2d7f8b0c 100644
--- a/tapset/memory.stp
+++ b/tapset/memory.stp
@@ -9,11 +9,11 @@
 
 /**
  * probe vm.pagefault - Records that a page fault occurred.
- * @address: The address of the faulting memory access.
- * @write_access: Indicates whether this was a write.
+ * @address: The address of the faulting memory access; i.e. the address that caused the page fault.
+ * @write_access: Indicates whether this was a write or read access; <command>1</command> indicates a write,
+ * while <command>0</command> indicates a read.
  *
  * Context: The process which triggered the fault
- *
  */
 probe vm.pagefault = kernel.function("__handle_mm_fault@mm/memory.c") ?,
                      kernel.function("handle_mm_fault@mm/memory.c") ?
@@ -23,9 +23,12 @@ probe vm.pagefault = kernel.function("__handle_mm_fault@mm/memory.c") ?,
 }
 
 /**
- * probe vm.pagefault.return - Records type of fault that occurred.
- * @fault_type: 0 (VM_FAULT_OOM), 1 (VM_FAULT_SIGBUS),
- * 		2 (VM_FAULT_MINOR), and 3 (VM_FAULT_MAJOR)
+ * probe vm.pagefault.return - Indicates what type of fault occurred.
+ * @fault_type: Returns either 
+ * <command>0</command> (VM_FAULT_OOM) for out of memory faults, 
+ * <command>2</command> (VM_FAULT_MINOR) for minor faults, <command>3</command> (VM_FAULT_MAJOR) for 
+ * major faults, or <command>1</command> (VM_FAULT_SIGBUS) if the fault was neither OOM, minor fault, 
+ * nor major fault.
  */
 probe vm.pagefault.return = kernel.function("__handle_mm_fault@mm/memory.c").return ?,
                             kernel.function("handle_mm_fault@mm/memory.c").return ?
@@ -34,7 +37,7 @@ probe vm.pagefault.return = kernel.function("__handle_mm_fault@mm/memory.c").ret
 }
 
 /**
- * sfunction addr_to_node - Returns which NUMA node has the given address.
+ * sfunction addr_to_node - Returns which node a given address belongs to within a NUMA system.
  * @addr: The address of the faulting memory access.
  *
  */
@@ -58,7 +61,7 @@ function _IS_ZERO_PAGE:long(from:long, vaddr:long) %{ /* pure */
 
 
 /**
- * probe vm.write_shared - Write to shared page.
+ * probe vm.write_shared - Attempts at writing to a shared page.
  * @address: The address of the shared write.
  *
  * Context:
@@ -66,7 +69,7 @@ function _IS_ZERO_PAGE:long(from:long, vaddr:long) %{ /* pure */
  *
  *  Fires when a process attempts to write to a shared page.
  *  If a copy is necessary, this will be followed by a
- *  vm.write_shared_copy.
+ *  <command>vm.write_shared_copy</command>.
  */
 probe vm.write_shared = kernel.function("do_wp_page") {
     address = $address
@@ -74,15 +77,15 @@ probe vm.write_shared = kernel.function("do_wp_page") {
 
 /**
  * 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
+ * @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 vm.shared_write.
+ *  always preceded by a <command>vm.shared_write</command>.
  */
 probe vm.write_shared_copy = kernel.function("copy_cow_page")? {
     address = $address
@@ -91,12 +94,12 @@ probe vm.write_shared_copy = kernel.function("copy_cow_page")? {
 
 
 /**
- * probe vm.mmap - Fires when an mmap is requested.
- * @address: the requested address
- * @length: the length of the memory segment 
+ * probe vm.mmap - Fires when an <command>mmap</command> is requested.
+ * @address: The requested address
+ * @length: The length of the memory segment 
  *
  * Context:
- *  The process calling mmap.
+ *  The process calling <command>mmap</command>.
  */
 probe vm.mmap = kernel.function("do_mmap"), kernel.function("do_mmap2")? {
     address = $addr
@@ -105,12 +108,12 @@ probe vm.mmap = kernel.function("do_mmap"), kernel.function("do_mmap2")? {
 
 
 /**
- * probe vm.munmap - Fires when an munmap is requested.
- * @address: the requested address
- * @length: the length of the memory segment 
+ * probe vm.munmap - Fires when an <command>munmap</command> is requested.
+ * @address: The requested address
+ * @length: The length of the memory segment 
  *
  * Context:
- *  The process calling munmap.
+ *  The process calling <command>munmap</command>.
  */
 probe vm.munmap = kernel.function("do_munmap") {
     address = $start
@@ -118,12 +121,12 @@ probe vm.munmap = kernel.function("do_munmap") {
 }
 
 /**
- * probe vm.brk - Fires when a brk is requested (resizing a heap).
- * @address: the requested address
- * @length: the length of the memory segment 
+ * probe vm.brk - Fires when a <command>brk</command> is requested (i.e. the heap will be resized).
+ * @address: The requested address
+ * @length: The length of the memory segment 
  *
  * Context:
- *  The process calling brk.
+ *  The process calling <command>brk</command>.
  */
 probe vm.brk = kernel.function("do_brk") {
     address = $addr
@@ -131,12 +134,12 @@ probe vm.brk = kernel.function("do_brk") {
 }
 
 /**
- * probe vm.oom_kill - Fires when a thread is targetted by the OOM killer.
- * @task: the task being killed
+ * probe vm.oom_kill - Fires when a thread is selected for termination by the OOM killer.
+ * @task: The task being killed
  *
  * Context:
- *  The process that tried to consume more memory, and thus
- *  triggered the OOM. (correct?)
+ *  The process that tried to consume excessive memory, and thus
+ *  triggered the OOM. <remark>(is this correct?)</remark>
  */
 probe vm.oom_kill = kernel.function("__oom_kill_task") {
     task = $p