Improve G_open|find _misc function documentation (#1760)

Lib GIS: improve documentation for G_file_name_misc, G_find_file_misc and G_fopen_(old|new)_misc

lib/gis/file_name.c

@@ -27,8 +27,31 @@ static void append_char(char*, char);
   If <i>name</i> is of the form "nnn@ppp" then path is set as if name
   had been "nnn" and mapset had been "ppp" (mapset parameter itself is
   ignored in this case).
-  
-  \param[out] path buffer to hold resultant full path to file
+
+  Paths to files are currently in form:
+  /path/to/location/mapset/element/name
+
+  path input buffer memory must be allocated by caller.
+
+  C:
+  @code{.c}
+  char path[GPATH_MAX];
+  G_file_name(path, "fcell", "my_raster", "my_mapset");
+  // path now is "/full/path/to/my_mapset/fcell/my_raster"
+  @endcode
+  Python:
+  @code{.py}
+  import ctypes
+  from grass.pygrass.utils import decode
+  from grass.lib.gis import G_file_name, GPATH_MAX
+
+  path = ctypes.create_string_buffer(GPATH_MAX)
+  path_str = decode(G_file_name(path, "elem", "name", "mapset"))
+  print(path_str)
+  >>> /full/path/to/mapset/elem/name
+  @endcode
+
+  \param[out] path allocated buffer to hold resultant full path to file
   \param element database element (eg, "cell", "cellhd", "vector", etc)
   \param name name of file to build path to (fully qualified names allowed)
   \param mapset mapset name
@@ -44,10 +67,33 @@ char *G_file_name(char *path,
 /*!
   \brief Builds full path names to GIS misc data files
 
-  \param[out] path buffer to hold resultant full path to file
-  \param dir misc directory
-  \param element database element (eg, "cell", "cellhd", "vector", etc)
-  \param name name of file to build path to (fully qualified names allowed)
+  Paths to misc files are currently in form:
+  /path/to/location/mapset/dir/name/element
+
+  path input buffer memory must be allocated by caller.
+
+  C:
+  @code{.c}
+  char path[GPATH_MAX];
+  G_file_name_misc(path, "cell_misc", "history", "my_raster", "my_mapset");
+  // path now contains "/full/path/to/my_mapset/cell_misc/my_raster/history"
+  @endcode
+  Python:
+  @code{.py}
+  import ctypes
+  from grass.pygrass.utils import decode
+  from grass.lib.gis import G_file_name_misc, GPATH_MAX
+
+  path = ctypes.create_string_buffer(GPATH_MAX)
+  path_str = decode(G_file_name_misc(path, "dir", "elem", "name", "mapset"))
+  print(path_str)
+  >>> /full/path/to/mapset/dir/name/elem
+  @endcode
+
+  \param[out] path allocated buffer to hold resultant full path to file
+  \param dir misc directory (e.g., "cell_misc", "group")
+  \param element database element (in this case – file to build path to e.g., "history", "REF")
+  \param name name of object (raster, group; fully qualified names allowed e.g., "my_raster@PERMANENT")
   \param mapset mapset name
 
   \return pointer to <i>path</i> buffer

lib/gis/find_file.c

@@ -206,10 +206,12 @@ const char *G_find_file(const char *element, char *name, const char *mapset)
 }
 
 /*!
- * \brief Searches for a file from the mapset search list or in a
+ * \brief Searches for a misc file from the mapset search list or in a
  * specified mapset.
  *
- * Returns the mapset name where the file was found.
+ * Returns the mapset name where the misc file was found.
+ * Paths to misc files currently follow structure:
+ * mapset/dir/name/element
  *
  * \param dir     file directory
  * \param element database element (eg, "cell", "cellhd", "colr", etc)
@@ -250,11 +252,12 @@ const char *G_find_file2(const char *element, const char *name, const char *maps
 }
 
 /*!
- * \brief Searches for a file from the mapset search list or in a
+ * \brief Searches for a misc file from the mapset search list or in a
  * specified mapset. (look but don't touch)
  *
- * Returns the mapset name where the file was found.
- *
+ * Returns the mapset name where the misc file was found.
+ * Paths to misc files currently follow structure:
+ * mapset/dir/name/element
  *
  * \param dir        file directory
  * \param element    database element (eg, "cell", "cellhd", "colr", etc)

lib/gis/open_misc.c

@@ -97,9 +97,9 @@ static int G__open_misc(const char *dir,
 
 
 /*!
- * \brief open a new database file
+ * \brief open a new database misc file
  *
- * The database file <b>name</b> under the <b>element</b> in the
+ * The database file <b>element</b> under <b>dir/name</b> in the
  * current mapset is created and opened for writing (but not reading).
  * The UNIX open( ) routine is used to open the file. If the file does not exist,
  * -1 is returned. Otherwise the file is positioned at the end of the file and
@@ -117,10 +117,10 @@ int G_open_new_misc(const char *dir, const char *element, const char *name)
 
 
 /*!
- * \brief open a database file for reading
+ * \brief open a database misc file for reading
  *
- * The database file <b>name</b> under the
- * <b>element</b> in the specified <b>mapset</b> is opened for reading (but
+ * The database file <b>element</b> under
+ * <b>dir/name</b> in the specified <b>mapset</b> is opened for reading (but
  * not for writing).
  * The UNIX open( ) routine is used to open the file. If the file does not exist,
  * -1 is returned. Otherwise the file descriptor from the open( ) is returned.
@@ -139,9 +139,9 @@ int G_open_old_misc(const char *dir, const char *element, const char *name,
 
 
 /*!
- * \brief open a database file for update
+ * \brief open a database misc file for update
  *
- * The database file <b>name</b> under the <b>element</b> in the
+ * The database file <b>element</b> under <b>dir/name</b> in the
  * current mapset is opened for reading and writing.
  * The UNIX open( ) routine is used to open the file. If the file does not exist,
  * -1 is returned. Otherwise the file is positioned at the end of the file and
@@ -165,9 +165,9 @@ int G_open_update_misc(const char *dir, const char *element, const char *name)
 
 
 /*!
- * \brief open a new database file
+ * \brief open a new database misc file
  *
- * The database file <b>name</b> under the <b>element</b> in the
+ * The database file <b>element</b> under <b>dir/name</b> in the
  * current mapset is created and opened for writing (but not reading).
  * The UNIX fopen( ) routine, with "w" write mode, is used to open the file.  If
  * the file does not exist, the NULL pointer is returned. Otherwise the file is
@@ -192,10 +192,10 @@ FILE *G_fopen_new_misc(const char *dir, const char *element, const char *name)
 
 
 /*!
- * \brief open a database file for reading
+ * \brief open a database misc file for reading
  *
- * The database file <b>name</b> under the
- * <b>element</b> in the specified <b>mapset</b> is opened for reading (but
+ * The database file <b>element</b> under
+ * <b>dir/name</b> in the specified <b>mapset</b> is opened for reading (but
  * not for writing).
  * The UNIX fopen( ) routine, with "r" read mode, is used to open the file.  If
  * the file does not exist, the NULL pointer is returned. Otherwise the file