From f1fdfd9f2cc256ba2ef02b5a2700a5ebe28f2388 Mon Sep 17 00:00:00 2001
From: Michael James Gratton <mike@vee.net>
Date: Mon, 5 Feb 2018 21:16:29 +1100
Subject: [PATCH] Update some API docs for Nonblocking.Lock and subclasses.

---
 src/engine/nonblocking/nonblocking-lock.vala  |  6 +++++-
 .../nonblocking/nonblocking-variants.vala     | 21 +++++++++++++++++++
 2 files changed, 26 insertions(+), 1 deletion(-)

diff --git a/src/engine/nonblocking/nonblocking-lock.vala b/src/engine/nonblocking/nonblocking-lock.vala
index 5ded2196..41c5df2d 100644
--- a/src/engine/nonblocking/nonblocking-lock.vala
+++ b/src/engine/nonblocking/nonblocking-lock.vala
@@ -16,7 +16,8 @@
  * pass. Another asynchronous task may call {@link notify} to mark the
  * lock as being safe, notifying waiting tasks. Once marked as being
  * safe to pass, a lock may be reset to being unsafe by calling {@link
- * reset}.
+ * reset}. The lock cannot be passed initially, if this is desired
+ * call notify after constructing it.
  *
  * See the specialised sub-classes for concrete implementations,
  * which vary based on two features:
@@ -84,6 +85,9 @@ public abstract class Geary.Nonblocking.Lock : BaseObject {
     private bool passed = false;
     private Gee.List<Pending> pending_queue = new Gee.LinkedList<Pending>();
 
+    /**
+     * Constructs a new lock that is initially not able to be passed.
+     */
     protected Lock(bool broadcast, bool autoreset, Cancellable? cancellable = null) {
         this.broadcast = broadcast;
         this.autoreset = autoreset;
diff --git a/src/engine/nonblocking/nonblocking-variants.vala b/src/engine/nonblocking/nonblocking-variants.vala
index 59e70d04..6a6b21c7 100644
--- a/src/engine/nonblocking/nonblocking-variants.vala
+++ b/src/engine/nonblocking/nonblocking-variants.vala
@@ -19,9 +19,16 @@
  * @see Lock
  */
 public class Geary.Nonblocking.Semaphore : Geary.Nonblocking.Lock {
+
+    /**
+     * Constructs a new semaphore lock.
+     *
+     * The new lock is initially not able to be passed.
+     */
     public Semaphore(Cancellable? cancellable = null) {
         base (true, false, cancellable);
     }
+
 }
 
 /**
@@ -37,9 +44,16 @@ public class Geary.Nonblocking.Semaphore : Geary.Nonblocking.Lock {
  * @see Lock
  */
 public class Geary.Nonblocking.Event : Geary.Nonblocking.Lock {
+
+    /**
+     * Constructs a new event lock.
+     *
+     * The new lock is initially not able to be passed.
+     */
     public Event(Cancellable? cancellable = null) {
         base (true, true, cancellable);
     }
+
 }
 
 /**
@@ -55,7 +69,14 @@ public class Geary.Nonblocking.Event : Geary.Nonblocking.Lock {
  * @see Lock
  */
 public class Geary.Nonblocking.Spinlock : Geary.Nonblocking.Lock {
+
+    /**
+     * Constructs a new spin lock.
+     *
+     * The new lock is initially not able to be passed.
+     */
     public Spinlock(Cancellable? cancellable = null) {
         base (false, true, cancellable);
     }
+
 }