[or-cvs] r17239: {tor} Document a couple of functions. (in tor/trunk/src: common or)

[nickm@xxxxxxxx]

Author: nickm
Date: 2008-11-10 15:40:01 -0500 (Mon, 10 Nov 2008)
New Revision: 17239

Modified:
   tor/trunk/src/common/compat.c
   tor/trunk/src/or/main.c
Log:
Document a couple of functions.

Modified: tor/trunk/src/common/compat.c
===================================================================
--- tor/trunk/src/common/compat.c	2008-11-10 15:53:07 UTC (rev 17238)
+++ tor/trunk/src/common/compat.c	2008-11-10 20:40:01 UTC (rev 17239)
@@ -476,12 +476,22 @@
   return 0;
 }
 
+/** Represents a lockfile on which we hold the lock. */
 struct tor_lockfile_t {
   char *filename;
   int fd;
 };
 
-/** DOCDOC. What's this function do? */
+/** Try to get a lock on the lockfile <b>filename</b>, creating it as
+ * necessary.  If someone else has the lock and <b>blocking</b> is true,
+ * wait until the lock is available.  Otherwise return immediately whether
+ * we succeeded or not.
+ *
+ * Set *<b>locked_out</b> to true if somebody else had the lock, and to false
+ * otherwise.
+ *
+ * Return a <b>tor_lockfile_t</b> on success, NULL on failure.
+ */
 tor_lockfile_t *
 tor_lockfile_lock(const char *filename, int blocking, int *locked_out)
 {
@@ -523,6 +533,7 @@
   return result;
 }
 
+/** Release the lock held as <b>lockfile</b>. */
 void
 tor_lockfile_unlock(tor_lockfile_t *lockfile)
 {

Modified: tor/trunk/src/or/main.c
===================================================================
--- tor/trunk/src/or/main.c	2008-11-10 15:53:07 UTC (rev 17238)
+++ tor/trunk/src/or/main.c	2008-11-10 20:40:01 UTC (rev 17239)
@@ -1861,7 +1861,11 @@
 
 static tor_lockfile_t *lockfile = NULL;
 
-/** DOCDOC. What's this function do? */
+/** Try to grab the lock file described in <b>options</b>, if we do not
+ * already have it.  If <b>err_if_locked</b> is true, warn if somebody else is
+ * holding the lock, and exit if we can't get it after waiting.  Otherwise,
+ * return -1 if we can't get the lockfile.  Return 0 on success.
+ */
 int
 try_locking(or_options_t *options, int err_if_locked)
 {