proclist, procarg and proctime gtkdoc updates

Added gtkdoc for proclist, procarg and proctime.

Author:    Tristan Hill <stan@saticed.me.uk>

https://bugzilla.gnome.org/show_bug.cgi?id=616082

2 files changed, 109 insertions, 18 deletions

diff --git a/include/glibtop/proclist.h b/include/glibtop/proclist.h
index 7859fe08..2fdbfb44 100644
--- a/include/glibtop/proclist.h
+++ b/include/glibtop/proclist.h
@@ -36,22 +36,89 @@ G_BEGIN_DECLS
 /* You can use the folowing constants as the `which' member of
  * glibtop_get_proclist () to specify which processes to fetch. */
 
-#define GLIBTOP_KERN_PROC_ALL		0	/* all processes */
+/**
+ * GLIBTOP_KERN_PROC_ALL:
+ *
+ * Return information about all processes
+ **/
+#define GLIBTOP_KERN_PROC_ALL		0
+
+/**
+ * GLIBTOP_KERN_PROC_PID:
+ *
+ * Return all processes with the pid which is passed in @arg. You can use this to find out whether some process still exists.
+ **/
 #define GLIBTOP_KERN_PROC_PID		1
+
+/**
+ * GLIBTOP_KERN_PROC_PGRP:
+ *
+ * Return all processes in the process group passed in @arg. 
+ **/
 #define GLIBTOP_KERN_PROC_PGRP		2
+
+/**
+ * GLIBTOP_KERN_PROC_SESSION:
+ *
+ * Return all processes in the session passed in @arg. 
+ **/
 #define GLIBTOP_KERN_PROC_SESSION	3
+
+/**
+ * GLIBTOP_KERN_PROC_TTY:
+ *
+ * Return all processes which have the controlling tty passed in @arg
+ * (which is interpreted as the device number). 
+ **/
 #define GLIBTOP_KERN_PROC_TTY		4
+
+/**
+ * GLIBTOP_KERN_PROC_UID:
+ *
+ * Return all processes with the effective uid passed in @arg. 
+ **/
 #define GLIBTOP_KERN_PROC_UID		5
+
+/**
+ * GLIBTOP_KERN_PROC_RUID:
+ *
+ * Return all processes with the real uid passed in @arg. 
+ **/
 #define GLIBTOP_KERN_PROC_RUID		6
 
 #define GLIBTOP_KERN_PROC_MASK		15
 
+
+/**
+ * GLIBTOP_EXCLUDE_IDLE:
+ *
+ * Exclude idle processes. 
+ **/
 #define GLIBTOP_EXCLUDE_IDLE		0x1000
+
+/**
+ * GLIBTOP_EXCLUDE_SYSTEM:
+ *
+ * Exclude system (on most UNIXes root's) processes.
+ **/
 #define GLIBTOP_EXCLUDE_SYSTEM		0x2000
+
+/**
+ * GLIBTOP_EXCLUDE_NOTTY:
+ *
+ * Exclude processes without a controlling terminal.
+ **/
 #define GLIBTOP_EXCLUDE_NOTTY		0x4000
 
 typedef struct _glibtop_proclist	glibtop_proclist;
 
+/**
+ * glibtop_proclist:
+ * @number: Number of entries in the returned list.
+ * @total: Total size of the returned list (this equals @number * @size).
+ * @size: Size of a single entry in the returned list 
+ * (this equals <type>sizeof(unsigned)</type>).
+ */
 struct _glibtop_proclist
 {
 	guint64	flags;
diff --git a/include/glibtop/proctime.h b/include/glibtop/proctime.h
index 5f542aea..cd22e2f5 100644
--- a/include/glibtop/proctime.h
+++ b/include/glibtop/proctime.h
@@ -46,26 +46,50 @@ typedef struct _glibtop_proc_time	glibtop_proc_time;
 
 /* Time section */
 
+/**
+ * glibtop_proc_time:
+ * @start_time: Start time of process in seconds since the epoch.
+ * @rtime: Real time accumulated by process (should be @utime + @stime).
+ * @utime: User-mode CPU time accumulated by process.
+ * @stime: Kernel-mode CPU time accumulated by process.
+ * @cutime: Cumulative utime of process and reaped children.
+ * @cstime: Cumulative stime of process and reaped children.
+ * @timeout: The time (in jiffies) of the process’s next timeout.
+ * @it_real_value: The time (in jiffies) before the next <type>SIGALRM</type>
+ * is sent to the process due to an interval timer.
+ * @frequency: Tick frequency.
+ * @xcpu_utime: SMP user-mode CPU time accumulated by process.
+ * @xcpu_stime: SMP kernel-mode CPU time accumulated by process 
+ *
+ * Process time data filled by glibtop_get_proc_time().
+ *
+ * Under Linux the @start_time value may be wrong due to the information
+ * available from the kernel.
+ * 
+ * The Linux kernel defines <type>INITIAL_JIFFIES</type> which implies a time
+ * shift. Because <type>INITIAL_JIFFIES</type> is not user-space defined,
+ * we cannot use it to compute an accurate @start_time. On Linux 2.6,
+ * <type>INITIAL_JIFFIES</type> is 300 so @start_time is 
+ * always 3s different from the real start time of the given process. You 
+ * may also get shift results if your system clock is not synchronised 
+ * with your hardware clock. See <command>man hwclock</command>.
+ */
 struct _glibtop_proc_time
 {
+    /*< private >*/
 	guint64	flags;
-	guint64 start_time;	/* start time of process --
-				 * seconds since 1-1-70 */
-	guint64 rtime;		/* real time accumulated by process */
-	guint64 utime;		/* user-mode CPU time accumulated by process */
-	guint64 stime;		/* kernel-mode CPU time accumulated by process */
-	guint64 cutime;		/* cumulative utime of process and
-				 * reaped children */
-	guint64 cstime;		/* cumulative stime of process and
-				 * reaped children */
-	guint64 timeout;	/* The time (in jiffies) of the process's
-				 * next timeout */
-	guint64 it_real_value;	/* The time (in jiffies) before the
-				 * next SIGALRM is sent to the process
-				 * due to an interval timer. */
-	guint64 frequency;	/* Tick frequency. */
-	guint64 xcpu_utime [GLIBTOP_NCPU];	/* utime and stime for all CPUs on */
-	guint64 xcpu_stime [GLIBTOP_NCPU];	/* SMP machines. */
+	/*< public >*/
+	guint64 start_time;
+	guint64 rtime;
+	guint64 utime;
+	guint64 stime;
+	guint64 cutime;
+	guint64 cstime;
+	guint64 timeout;
+	guint64 it_real_value;
+	guint64 frequency;
+	guint64 xcpu_utime [GLIBTOP_NCPU];
+	guint64 xcpu_stime [GLIBTOP_NCPU];
 };