Fix and document rig_cookie;

Example in doxygen was wrong.
Description of parameters was wrong; we return an int so we cannot return
a NULL.
NULL check for cookies is needed for all 3 commands so move it up, fixing the
missing one.
Length check was wrong; cookie needs to be at least as large as
HAMLIB_COOKIE_SIZE otherwise subsequent checks will always faila
Document the 3 cookie commands a bit.

include/hamlib/rig.h

@@ -1000,9 +1000,9 @@ enum rig_parm_e {
  *
  */
 enum cookie_e {
-    RIG_COOKIE_GET,
-    RIG_COOKIE_RELEASE,
-    RIG_COOKIE_RENEW,
+    RIG_COOKIE_GET,     /*!< Setup a cookie */
+    RIG_COOKIE_RELEASE, /*!< Release a cookie */
+    RIG_COOKIE_RENEW,   /*!< Renew a cookie */
 };
 
 /**

src/rig.c

@@ -6763,17 +6763,27 @@ const char *HAMLIB_API rig_copyright()
 
 /**
  * \brief get a cookie to grab rig control
+ * \param rig   Not used
+ * \param cookie_cmd The command to execute on \a cookie.
+ * \param cookie     The cookie to operate on, cannot be NULL or RIG_EINVAL will be returned.
+ * \param cookie_len The length of the cookie, must be #HAMLIB_COOKIE_SIZE or larger.
+ *
+ * #RIG_COOKIE_GET will set \a cookie with a cookie.
+ * #RIG_COOKIE_RENEW will update the timeout with 1 second.
+ * #RIG_COOKIE_RELEASE will release the cookie and allow a new one to be grabbed.
  *
- * RIG_COOKIE_GET must have cookie=NULL or NULL returned
- * RIG_COOKIE_RENEW must have cookie!=NULL or NULL returned
- * RIG_COOKIE_RELEASE must have cookie!=NULL or NULL returned;
  * Cookies should only be used when needed to keep commands sequenced correctly
  * For example, when setting both VFOA and VFOB frequency and mode
  * Example to wait for cookie, do rig commands, and release
- * while((cookie=rig_cookie(NULL, RIG_COOKIE_GET)) == NULL) hl_usleep(10*1000);
+ * \code
+ *  while((rig_cookie(NULL, RIG_COOKIE_GET, cookie, sizeof(cookie))) != RIG_OK)
+ *      hl_usleep(10*1000);
+ *
+ *  //Pseudo code
  *  set_freq A;set mode A;set freq B;set modeB;
- * rig_cookie(cookie,RIG_COOKIE_RELEASE);
- * if wait!=0 rig_cookie with RIG_COOKIE_GET will wait for the cookie to become available
+ *
+ *  rig_cookie(NULL, RIG_COOKIE_RELEASE, cookie, sizeof(cookie)));
+ * \endcode
  */
 int HAMLIB_API rig_cookie(RIG *rig, enum cookie_e cookie_cmd, char *cookie,
                           int cookie_len)
@@ -6791,27 +6801,27 @@ int HAMLIB_API rig_cookie(RIG *rig, enum cookie_e cookie_cmd, char *cookie,
     static pthread_mutex_t cookie_lock = PTHREAD_MUTEX_INITIALIZER;
 #endif
 
-    if (cookie_len < 27)
+    if (cookie_len < HAMLIB_COOKIE_SIZE)
     {
-        rig_debug(RIG_DEBUG_ERR, "%s(%d): cookie_len < 32 so returning NULL!!\n",
+        rig_debug(RIG_DEBUG_ERR, "%s(%d): cookie_len < %d\n",
+                  __FILE__, __LINE__, HAMLIB_COOKIE_SIZE);
+        return -RIG_EINVAL;
+    }
+
+    if (!cookie)
+    {
+        rig_debug(RIG_DEBUG_ERR, "%s(%d): cookie == NULL\n",
                 __FILE__, __LINE__);
-        return -RIG_EINTERNAL;
+        return -RIG_EINVAL; // nothing to do
     }
 
     switch (cookie_cmd)
     {
     case RIG_COOKIE_RELEASE:
-        if (cookie == NULL)
-        {
-            rig_debug(RIG_DEBUG_VERBOSE, "%s(%d): coookie NULL so nothing to do\n",
-                      __FILE__, __LINE__);
-            return -RIG_EINVAL; // nothing to do
-        }
-
         if (cookie_save[0] != 0
                 && strcmp(cookie, cookie_save) == 0) // matching cookie so we'll clear it
         {
-            rig_debug(RIG_DEBUG_VERBOSE, "%s(%d): %s coookie released\n",
+            rig_debug(RIG_DEBUG_VERBOSE, "%s(%d): %s cookie released\n",
                       __FILE__, __LINE__, cookie_save);
             memset(cookie_save, 0, sizeof(cookie_save));
             return RIG_OK;
@@ -6894,7 +6904,7 @@ int HAMLIB_API rig_cookie(RIG *rig, enum cookie_e cookie_cmd, char *cookie,
         break;
     }
 
-    rig_debug(RIG_DEBUG_ERR, "%s(%d): unknown condition!!\n'", __FILE__, __LINE__);
+    rig_debug(RIG_DEBUG_ERR, "%s(%d): unknown cmd!!\n'", __FILE__, __LINE__);
     return -RIG_EPROTO;
 }