From 9495b9ae90634603fb390ff56da459e3c8137a63 Mon Sep 17 00:00:00 2001
From: Adam Dickmeiss <adam@indexdata.dk>
Date: Wed, 20 Feb 2008 10:03:42 +0000
Subject: [PATCH] Describe YAZ' options function.

---
 include/yaz/options.h |   27 +++++++++++++++++++++++----
 src/options.c         |    4 ++--
 2 files changed, 25 insertions(+), 6 deletions(-)

diff --git a/include/yaz/options.h b/include/yaz/options.h
index b046364..ccf6d9c 100644
--- a/include/yaz/options.h
+++ b/include/yaz/options.h
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1995-2007, Index Data
+ * Copyright (c) 1995-2008, Index Data
  * All rights reserved.
  * Redistribution and use in source and binary forms, with or without
  * modification, are permitted provided that the following conditions are met:
@@ -24,19 +24,38 @@
  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
  * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  */
-/* $Id: options.h,v 1.8 2007-01-03 08:42:14 adam Exp $ */
+/* $Id: options.h,v 1.9 2008-02-20 10:03:42 adam Exp $ */
 
 /**
  * \file options.h
  * \brief Header for command line options parsing utilities
  */
 
-#ifndef OPTIONS_H
-#define OPTIONS_H
+#ifndef YAZ_OPTIONS_H
+#define TAZ_OPTIONS_H
 #include <yaz/yconfig.h>
 
 YAZ_BEGIN_CDECL
 
+/** \brief parser command-line options
+    \arg desc command argument description (allowed options)
+    \arg argv main argv
+    \arg argc main argc
+    \arg arg returned argument (for options that take an argument).
+    \retval 0 non-option arg (e.g. filename).
+    \retval -1 unknown option (error). arg is name of unknown option
+    \retval -2 no more options (end of options)
+    \retval c option char
+    
+    This function is called repeatedly for each option. Both single
+    char options (-x) as well as GNU long options are supported (--long).
+    The description is a sequence specs where each spec is if the form: 
+    [a-zA-Z0-9]({[a-zA-Z0-9]*})+:? . For example: h{help}f{filename}{fname}:
+
+    The first char is what is returned when met (single char option char).
+    The second is zero ore more long option values (synonum for single char)
+    If colon is appended, it means the option takes an argument.
+*/
 YAZ_EXPORT int options (const char *desc, char **argv, int argc, char **arg);
 
 YAZ_END_CDECL
diff --git a/src/options.c b/src/options.c
index 3125735..e66b13e 100644
--- a/src/options.c
+++ b/src/options.c
@@ -2,7 +2,7 @@
  * Copyright (C) 1995-2007, Index Data ApS
  * See the file LICENSE for details.
  *
- * $Id: options.c,v 1.6 2008-02-19 19:58:40 adam Exp $
+ * $Id: options.c,v 1.7 2008-02-20 10:03:42 adam Exp $
  */
 /**
  * \file options.c
@@ -67,7 +67,7 @@ int options (const char *desc, char **argv, int argc, char **arg)
                 i++;
         }
         if (desc[i] == ':')
-        {       /* string argument */
+        {       /* option with string argument */
                 type = desc[i++];
         }
         if (desc_char == ch)
-- 
1.7.10.4