libgis: attempt to document G_mkstemp() etc according to http://lists.osgeo.org/pipermail/grass-dev/2014-January/066964.html

git-svn-id: https://svn.osgeo.org/grass/grass/trunk@58834 15284696-431f-4ddb-bdfa-cd5b030d7da7

lib/gis/mkstemp.c

@@ -1,3 +1,16 @@
+/*!
+ * \file lib/gis/mkstemp.c
+ *
+ * \brief GIS Library - Temporary file functions.
+ *
+ * (C) 2014 by the GRASS Development Team
+ *
+ * This program is free software under the GNU General Public License
+ * (>=v2). Read the file COPYING that comes with GRASS for details.
+ *
+ * \author Glynn Clements
+ */
+
 #include <stdio.h>
 #include <string.h>
 #include <errno.h>
@@ -68,11 +81,49 @@ static int G__mkstemp(char *template, int flags, int mode)
 }
 
 
+/*!
+ * \brief Opens a temporary file.
+ *
+ * This routine opens the file.
+ *
+ * The last two take the arguments "flags" and "mode". "flags" should be
+ * O_WRONLY or O_RDWR, plus any other desired flags (e.g. O_APPEND).
+ * "mode" is the file mode (0666 would be typical).
+ *
+ * The functions does not use the PID, although the caller can do so.
+ *
+ * In theory, up to 26^5 (= ~12 million) filenames will be attempted
+ * until it finds one which doesn't exist.
+ *
+ * <b>Note:</b> <i>G_mktemp()</i> as such it is prone to race
+ * conditions (some other process may create that file after G_mktemp()
+ * returns).
+ *
+ * \return file name
+ */
 char *G_mktemp(char *template)
 {
     return G__mkstemp(template, 0, 0) < 0 ? NULL : template;
 }
 
+/*!
+ * \brief Returns a file descriptor.
+ *
+ * This routine opens the file and returns a descriptor.
+ *
+ * The last two take the arguments "flags" and "mode". "flags" should be
+ * O_WRONLY or O_RDWR, plus any other desired flags (e.g. O_APPEND).
+ * "mode" is the file mode (0666 would be typical).
+ *
+ * The functions does not use the PID, although the caller can do so.
+ *
+ * In theory, up to 26^5 (= ~12 million) filenames will be attempted
+ * until it finds one which doesn't exist.
+ *
+ *
+ * \return file descriptor
+ */
+
 int G_mkstemp(char *template, int flags, int mode)
 {
 
@@ -91,6 +142,23 @@ int G_mkstemp(char *template, int flags, int mode)
     return G__mkstemp(template, flags | O_CREAT | O_EXCL, mode);
 }
 
+/*!
+ * \brief Returns a file descriptor.
+ *
+ * This routine opens the file and returns a FILE*.
+ *
+ * The last two take the arguments "flags" and "mode". "flags" should be
+ * O_WRONLY or O_RDWR, plus any other desired flags (e.g. O_APPEND).
+ * "mode" is the file mode (0666 would be typical).
+ *
+ * The functions does not use the PID, although the caller can do so.
+ *
+ * In theory, up to 26^5 (= ~12 million) filenames will be attempted
+ * until it finds one which doesn't exist.
+ *
+ * \return FILE*
+ */
+
 FILE *G_mkstemp_fp(char *template, int flags, int mode)
 {
     const char *fmode = (flags & O_ACCMODE == O_RDWR)