From 0858cbfc16aaf52d7a0de9e2cfb04ce57538cf47 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?B=C3=A5rd=20Skaflestad?= <Bard.Skaflestad@sintef.no>
Date: Wed, 18 Jul 2012 12:05:53 +0200
Subject: [PATCH] Document public interface of Cartesian grid constructors.

---
 opm/core/grid/cart_grid.h | 127 +++++++++++++++++++++++++++++++++++---
 1 file changed, 119 insertions(+), 8 deletions(-)

diff --git a/opm/core/grid/cart_grid.h b/opm/core/grid/cart_grid.h
index b11898a2..19fbad6c 100644
--- a/opm/core/grid/cart_grid.h
+++ b/opm/core/grid/cart_grid.h
@@ -30,25 +30,136 @@
 #ifndef OPM_CART_GRID_H_HEADER
 #define OPM_CART_GRID_H_HEADER
 
+/**
+ * \file
+ * Routines to construct fully formed grid structures from a simple Cartesian
+ * (i.e., tensor product) description.
+ *
+ * The cells are lexicographically ordered with the @c i index cycling the most
+ * rapidly, followed by the @c j index and then, in three space dimensions, the
+ * @c k (`layer') index as the least rapidly cycling index.
+ */
+
 #ifdef __cplusplus
 extern "C" {
 #endif
 
 struct UnstructuredGrid;
 
-struct UnstructuredGrid *create_grid_cart2d(int nx, int ny);
-struct UnstructuredGrid *create_grid_cart3d(int nx, int ny, int nz);
-struct UnstructuredGrid *create_grid_hexa3d(int nx, int ny, int nz,
-					     double dx, double dy, double dz);
+/**
+ * Form geometrically Cartesian grid in two space dimensions with unit-sized
+ * cells.
+ *
+ * @param[in] nx Number of cells in @c x direction.
+ * @param[in] ny Number of cells in @c y direction.
+ *
+ * @return Fully formed grid structure containing valid geometric primitives.
+ * Must be destroyed using function destroy_grid().
+ */
+struct UnstructuredGrid *
+create_grid_cart2d(int nx, int ny);
 
-struct UnstructuredGrid *create_grid_tensor2d(int nx, int ny,
-                                              double x[], double y[]);
+
+/**
+ * Form geometrically Cartesian grid in three space dimensions with unit-sized
+ * cells.
+ *
+ * @param[in] nx Number of cells in @c x direction.
+ * @param[in] ny Number of cells in @c y direction.
+ * @param[in] nz Number of cells in @c z direction.
+ *
+ * @return Fully formed grid structure containing valid geometric primitives.
+ * Must be destroyed using function destroy_grid().
+ */
+struct UnstructuredGrid *
+create_grid_cart3d(int nx, int ny, int nz);
+
+
+/**
+ * Form geometrically Cartesian grid in three space dimensions with equally
+ * sized cells.
+ *
+ * Each cell has physical size (volume) \f$\mathit{dx}\times \mathit{dy}\times
+ * \mathit{dz}\f$.
+ *
+ * @param[in] nx Number of cells in @c x direction.
+ * @param[in] ny Number of cells in @c y direction.
+ * @param[in] nz Number of cells in @c z direction.
+ *
+ * @param[in] dx Length, in meters, of each cell's @c x extent.
+ * @param[in] dy Length, in meters, of each cell's @c y extent.
+ * @param[in] dz Length, in meters, of each cell's @c z extent.
+ *
+ * @return Fully formed grid structure containing valid geometric primitives.
+ * Must be destroyed using function destroy_grid().
+ */
+struct UnstructuredGrid *
+create_grid_hexa3d(int nx, int ny, int nz,
+                   double dx, double dy, double dz);
+
+
+/**
+ * Form tensor product (Cartesian) grid in two space dimensions.
+ *
+ * The size (volume) of cell \f$(i,j)\f$ is
+ * \f[
+ * v_{ij} = (x_{i+1} - x_i)\cdot (y_{j+1} - y_j)
+ * \f]
+ * Similar relations hold for the cell and interface centroids as well as the
+ * interface areas and normal vectors. In other words, cell \f$(i,j)\f$ is the
+ * convex hull bounded by the tensor product of nodes \f$x_i\f$, \f$x_{i+1}\f$,
+ * \f$y_j\f$, and \f$y_{j+1}\f$.
+ *
+ * @param[in] nx Number of cells in @c x direction.
+ * @param[in] ny Number of cells in @c y direction.
+ *
+ * @param[in] x  Position along @c x axis of each grid line with constant @c x
+ *               coordinate.  Array of size <CODE>nx + 1</CODE>.
+ * @param[in] y  Position along @c y axis of each grid line with constant @c y
+ *               coordinate.  Array of size <CODE>ny + 1</CODE>.
+ *
+ * @return Fully formed grid structure containing valid geometric primitives.
+ * Must be destroyed using function destroy_grid().
+ */
+struct UnstructuredGrid *
+create_grid_tensor2d(int nx, int ny,
+                     double x[], double y[]);
+
+
+/**
+ * Form tensor product (i.e., topologically Cartesian) grid in three space
+ * dimensions--possibly with a variable top-layer topography.
+ *
+ * If @c depthz is @c NULL, then geometric information such as volumes and
+ * centroids is calculated from analytic expressions.  Otherwise, these values
+ * are computed using function compute_geometry().
+ *
+ * @param[in] nx Number of cells in @c x direction.
+ * @param[in] ny Number of cells in @c y direction.
+ * @param[in] nz Number of cells in @c z direction.
+ *
+ * @param[in] x  Position along @c x axis of each grid line with constant @c x
+ *               coordinate.  Array of size <CODE>nx + 1</CODE>.
+ * @param[in] y  Position along @c y axis of each grid line with constant @c y
+ *               coordinate.  Array of size <CODE>ny + 1</CODE>.
+ * @param[in] z  Distance (depth) from top-layer measured along the @c z axis of
+ *               each grid line with constant @c z coordinate.  Array of size
+ *               <CODE>nz + 1</CODE>.
+ *
+ * @param[in] depthz
+ *               Top-layer topography specification.  If @c NULL, interpreted as
+ *               horizontal top-layer at <CODE>z=0</CODE>.  Otherwise, must be
+ *               an array of size <CODE>(nx + 1) * (ny + 1)</CODE>, ordered
+ *               lexicographically, that defines the depth of each top-layer
+ *               pillar vertex.
+ *
+ * @return Fully formed grid structure containing valid geometric primitives.
+ * Must be destroyed using function destroy_grid().
+ */
 struct UnstructuredGrid *
 create_grid_tensor3d(int nx, int ny, int nz,
                      double x[], double y[], double z[],
                      const double depthz[]);
-
-
 #ifdef __cplusplus
 }
 #endif