From 6da5d38dde2e05a33ce9fbc01ce700b117a6fff2 Mon Sep 17 00:00:00 2001
From: Ward Fisher <wfisher@ucar.edu>
Date: Fri, 8 Jul 2016 15:38:05 -0600
Subject: [PATCH] Started filling out group documentation. See
 https://github.com/Unidata/netcdf-c/issues/277 for more information.

---
 libdispatch/dgroup.c | 41 ++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 40 insertions(+), 1 deletion(-)

diff --git a/libdispatch/dgroup.c b/libdispatch/dgroup.c
index 5952bb956..59a12bc28 100644
--- a/libdispatch/dgroup.c
+++ b/libdispatch/dgroup.c
@@ -40,7 +40,8 @@ than 32767.  Similarly, the number of simultaneously open netCDF-4
 files in one program context is limited to 32767.
 
  */
-/** \{ */
+
+/** \{*/ /* All these functions are part of the above defgroup... */
 
 /*!
 
@@ -131,6 +132,43 @@ int nc_inq_typeids(int ncid, int *ntypes, int *typeids)
     return ncp->dispatch->inq_typeids(ncid,ntypes,typeids);
 }
 
+/*!
+
+Define a new group.  The function nc_def_grp adds a new
+group to an open netCDF dataset in define mode.  It returns (as an
+ argument) a group id, given the parent ncid and the name of the group.
+
+A group may be a top-level group if it is passed the ncid of the file,
+or a sub-group if passed the ncid of an existing group.
+
+@param[in]  parent_ncid The ncid of the parent for the group.
+@param[in]  name        Name of the new group.
+@param[out] new_ncid    Pointer to memory to hold the new ncid.
+
+@returns Error code or 0 for no error.
+
+@retval ::NC_NOERR No error.
+@retval ::NC_ENOTNC4 Not an nc4 file.
+@retval ::NC_ENOTINDEFINE Not in define mode.
+@retval ::NC_ESTRICTNC3 Not permissible in nc4 classic mode.
+@retval ::NC_EPERM Write to read only.
+@retval ::NC_ENOMEM Memory allocation (malloc) failure.
+@retval ::NC_ENAMEINUSE String match to name in use.
+
+\section nc_def_grp_example Example
+
+Here is an example using nc_def_grp() to create a new group.
+
+\code{.c}
+
+#include <netcdf.h>
+...
+int status, ncid, grpid, latid, recid;
+...
+
+\endcode
+
+*/
 int nc_def_grp(int parent_ncid, const char *name, int *new_ncid)
 {
     NC* ncp;
@@ -139,6 +177,7 @@ int nc_def_grp(int parent_ncid, const char *name, int *new_ncid)
     return ncp->dispatch->def_grp(parent_ncid,name,new_ncid);
 }
 
+
 int nc_rename_grp(int grpid, const char *name)
 {
     NC* ncp;