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

4 files changed, 168 insertions, 65 deletions

diff --git a/doc/reference/libgtop-sections.txt b/doc/reference/libgtop-sections.txt
index 0d99d695..ba878943 100644
--- a/doc/reference/libgtop-sections.txt
+++ b/doc/reference/libgtop-sections.txt
@@ -219,17 +219,8 @@ glibtop_set_parameter_l
 <INCLUDE>glibtop/procargs.h</INCLUDE>
 <SECTION>
 <FILE>procargs</FILE>
-GLIBTOP_PROC_ARGS_SIZE
-GLIBTOP_MAX_PROC_ARGS
 glibtop_proc_args
-glibtop_get_proc_args_l
 glibtop_get_proc_args
-glibtop_get_proc_args_r
-glibtop_init_proc_args_p
-glibtop_get_proc_args_p
-glibtop_init_proc_args_s
-glibtop_get_proc_args_s
-glibtop_get_proc_argv_l
 glibtop_get_proc_argv
 </SECTION>
 
@@ -420,26 +411,8 @@ glibtop_get_proc_uid_s
 <INCLUDE>glibtop/proctime.h</INCLUDE>
 <SECTION>
 <FILE>proctime</FILE>
-GLIBTOP_PROC_TIME_START_TIME
-GLIBTOP_PROC_TIME_RTIME
-GLIBTOP_PROC_TIME_UTIME
-GLIBTOP_PROC_TIME_STIME
-GLIBTOP_PROC_TIME_CUTIME
-GLIBTOP_PROC_TIME_CSTIME
-GLIBTOP_PROC_TIME_TIMEOUT
-GLIBTOP_PROC_TIME_IT_REAL_VALUE
-GLIBTOP_PROC_TIME_FREQUENCY
-GLIBTOP_PROC_TIME_XCPU_UTIME
-GLIBTOP_PROC_TIME_XCPU_STIME
-GLIBTOP_MAX_PROC_TIME
 glibtop_proc_time
 glibtop_get_proc_time
-glibtop_get_proc_time_r
-glibtop_get_proc_time_l
-glibtop_init_proc_time_p
-glibtop_get_proc_time_p
-glibtop_init_proc_time_s
-glibtop_get_proc_time_s
 </SECTION>
 
 <INCLUDE>glibtop/signal.h</INCLUDE>
@@ -515,10 +488,6 @@ glibtop_send_version
 <INCLUDE>glibtop/proclist.h</INCLUDE>
 <SECTION>
 <FILE>proclist</FILE>
-GLIBTOP_PROCLIST_NUMBER
-GLIBTOP_PROCLIST_TOTAL
-GLIBTOP_PROCLIST_SIZE
-GLIBTOP_MAX_PROCLIST
 GLIBTOP_KERN_PROC_ALL
 GLIBTOP_KERN_PROC_PID
 GLIBTOP_KERN_PROC_PGRP
@@ -532,12 +501,6 @@ GLIBTOP_EXCLUDE_SYSTEM
 GLIBTOP_EXCLUDE_NOTTY
 glibtop_proclist
 glibtop_get_proclist
-glibtop_get_proclist_r
-glibtop_get_proclist_l
-glibtop_init_proclist_p
-glibtop_get_proclist_p
-glibtop_init_proclist_s
-glibtop_get_proclist_s
 </SECTION>
 
 <INCLUDE>glibtop/sem_limits.h</INCLUDE>
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];
 };
 
 
diff --git a/sysdeps/common/default.c b/sysdeps/common/default.c
index 71db0746..2df25ee6 100644
--- a/sysdeps/common/default.c
+++ b/sysdeps/common/default.c
@@ -135,18 +135,18 @@ glibtop_get_proc_uid(glibtop_proc_uid *buf, pid_t pid)
 
 
 /**
+ * SECTION:proctime
+ * @title: Process Time
+ * @short_description: Get process time information
+ * @stability: Stable
+ */
+
+/**
  * glibtop_get_proc_time:
- * @buf:
- * @pid: Process id to get the user and tty information
+ * @buf: Returned process time information - see #glibtop_proc_time.
+ * @pid: Process id
  *
- * Please note that under Linux, #start_time value may be strange.
- * 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 accurate @code{start_time}. On Linux2.6,
- * <type>INITIAL_JIFFIES</type> is 300 so <type>start_time</type> is 
- * always 3s different from 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>.
+ * Get process time information.
  */
 void
 glibtop_get_proc_time(glibtop_proc_time *buf, pid_t pid)
@@ -197,6 +197,26 @@ glibtop_get_proc_map(glibtop_proc_map *buf, pid_t pid)
 }
 
 
+/**
+ * SECTION:procargs
+ * @title: Process Arguments
+ * @short_description: Get process command line arguments
+ * @see_also: #libgtop-Process-List
+ * @stability: Stable
+ */
+
+/**
+ * glibtop_get_proc_args:
+ * @buf: Struct with @size of returned string.
+ * @pid: Process id
+ * @max_len: Maximum length of string to return (use zero to get all arguments).
+ *
+ * Get process command line arguments.
+ *
+ * Returns: @pid's command line arguments separated by null bytes; the length of 
+ * this string is returned in the @buf size field.  You are required to free
+ * the string when done.
+ */
 char *
 glibtop_get_proc_args(glibtop_proc_args *buf, pid_t pid, unsigned max_len)
 {
@@ -204,6 +224,18 @@ glibtop_get_proc_args(glibtop_proc_args *buf, pid_t pid, unsigned max_len)
 }
 
 
+/**
+ * glibtop_get_proc_argv
+ * @buf: Struct with @size of combined returned arguments.
+ * @pid: Process id
+ * @max_len: Maximum length of all arguments combined (use zero to get all arguments).
+ *
+ * Get process command line arguments.
+ *
+ * Returns: A NULL-terminated array of strings with all arguments of process pid
+ * (up to @max_len characters).  Remember to <function>g_strfreev</function>
+ * the returned array to avoid a memory leak.
+ */
 char **
 glibtop_get_proc_argv(glibtop_proc_args *buf, pid_t pid, unsigned max_len)
 {
@@ -211,6 +243,23 @@ glibtop_get_proc_argv(glibtop_proc_args *buf, pid_t pid, unsigned max_len)
 }
 
 
+/**
+ * SECTION:proclist
+ * @title: Process List
+ * @short_description: List running processes
+ * @stability: Stable
+ */
+
+/**
+ * glibtop_get_proclist
+ * @buf: Extra return information, see #glibtop_proclist.
+ * @which: Criteria for processes in returned list.  See the <type>GLIBTOP_KERN_PROC_*</type> and <type>GLIBTOP_EXCLUDE_*</type> constants.
+ * @arg: Extra arguments applied to @which.  Only <type>GLIBTOP_KERN_PROC_*</type> constants take arguments, see each constant definition for particular @arg description.
+ *
+ * Returns: A list of running processes or <type>NULL</type> on error.  The
+ * returned list is allocated using <function>g_malloc</function> and must be
+ * freed using <function>g_free</function> to avoid a memory leak.
+ */
 pid_t*
 glibtop_get_proclist(glibtop_proclist *buf, gint64 which, gint64 arg)
 {