dox: region (window) functions doc improvements

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

lib/gis/adj_cellhd.c

@@ -34,8 +34,6 @@
  * \param[in,out] cellhd pointer to Cell_head structure
  * \param row_flag compute n-s resolution
  * \param col_flag compute e-w resolution
-
- * \return NULL on success
  */
 void G_adjust_Cell_head(struct Cell_head *cellhd, int row_flag, int col_flag)
 {
@@ -177,12 +175,13 @@ void G_adjust_Cell_head(struct Cell_head *cellhd, int row_flag, int col_flag)
  * If <i>depth_flag</i> are false, number of depths is calculated from 
  * top-bottom resolution.
  *
+ * \warning This function can cause segmentation fault without any warning
+ * when it is called with Cell_head top and bottom set to zero.
+ *
  * \param[in,out] cellhd pointer to Cell_head structure
  * \param row_flag compute n-s resolution
  * \param col_flag compute e-w resolution
  * \param depth_flag compute t-b resolution
- *
- * \return NULL on success
  */
 void G_adjust_Cell_head3(struct Cell_head *cellhd, int row_flag,
 			 int col_flag, int depth_flag)

lib/gis/put_window.c

@@ -15,20 +15,31 @@
 #include <grass/gis.h>
 
 /*!
- * \brief Write the database region
+ * \brief Writes the database region (window)
  *
  * Writes the database region file (WIND) in the user's current mapset
- * from region. 
-
- * <b>Warning:</b> Since this routine actually changes the database
- * region, it should only be called by modules which the user knows
+ * or when environmental variable \c WIND_OVERRIDE is set,
+ * it writes the region to file specified by \c WIND_OVERRIDE variable.
+ *
+ * When \c WIND_OVERRIDE is set the current process and child processes
+ * are affected.
+ * Otherwise the whole GRASS session is affected.
+ *
+ * \warning When environmental variable \c WIND_OVERRIDE is not set,
+ * this routine actually changes the database region.
+ * So in this case it should only be called by modules which the user knows
  * will change the region. It is probably fair to say that only the
- * <tt>g.region</tt>.
+ * \gmod{g.region} should call this routine unless \c WIND_OVERRIDE is set.
+ *
+ * This function does not adjust the \p window before setting the region
+ * so you should call G_adjust_Cell_head() before calling this function.
  *
  * \param[in,out] window pointer to Cell_head
  *
  * \return 1 on success
  * \return -1 on error (no diagnostic message is printed)
+ *
+ * \sa G_get_window(), G_set_window(), python.core.use_temp_region()
  */
 int G_put_window(const struct Cell_head *window)
 {
@@ -47,7 +58,7 @@ int G_put_window(const struct Cell_head *window)
  * <b>Warning:</b> Since this routine actually changes the database
  * region, it should only be called by modules which the user knows
  * will change the region. It is probably fair to say that only the
- * <tt>g.region</tt>.
+ * <tt>g.region</tt> should call this routine.
  *
  * \param[in,out] window pointer to Cell_head
  * \param dir directory name
@@ -55,6 +66,8 @@ int G_put_window(const struct Cell_head *window)
  *
  * \return 1 on success
  * \return -1 on error (no diagnostic message is printed)
+ *
+ * \sa G_put_window()
  */
 int G__put_window(const struct Cell_head *window, const char *dir, const char *name)
 {

lib/gis/set_window.c

@@ -18,11 +18,17 @@
 
 /*!
   \brief Get the current working window (region)
-  
+
   The current working window values are returned in the structure
-  <i>window</i>.
-  
-  \param[out] window window structure to be set
+  \p window.
+
+  Previous calls to G_set_window() affects values returned by this function.
+  Previous calls to G_put_window() affects values returned by this function
+  only if the current working window is not initialized.
+
+  \param[out] window pointer to window structure to be set
+
+  \sa G_set_window(), G_get_window()
 */
 void G_get_set_window(struct Cell_head *window)
 {
@@ -31,9 +37,16 @@ void G_get_set_window(struct Cell_head *window)
 }
 
 /*!
-  \brief Establishes 'window' as the current working window.
-  
+  \brief Establishes \p window as the current working window (region).
+
+  This function adjusts the \p window before setting the region
+  so you don't have to call G_adjust_Cell_head().
+
+  \note Only the current process is affected.
+
   \param window window to become operative window
+
+  \sa G_get_set_window(), G_put_window()
 */
 void G_set_window(struct Cell_head *window)
 {