Merge pull request #3276 from edhartnett/ejh_more_docs_0219

documentation fixes for liblib and examples

Author: WardF

examples/C/file.c

@@ -1,24 +1,18 @@
-/*! \file
-
-Copyright 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002,
-2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014,
-2015, 2016, 2017, 2018
-University Corporation for Atmospheric Research/Unidata.
-
-See \ref copyright file for more info.
-
-*/
-
-
-/* This example program is part of Unidata's netCDF library for
-   scientific data access.
-
-   This program demonstrates various ways to create a netCDF file,
-   open an existing file, and close a file.
-
-   Ed Hartnett, 5/29/4
-   $Id: file.c,v 1.1 2004/07/26 14:04:42 ed Exp $
-*/
+/* Copyright 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002,
+   2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014,
+   2015, 2016, 2017, 2018 University Corporation for Atmospheric
+   Research/Unidata.  See COPYRIGHT file for conditions of use. */
+/**
+ * @file
+ * Demonstrate the full create, write, reopen, and read cycle.
+ *
+ * This example program is part of Unidata's netCDF library for
+ * scientific data access. It creates a netCDF file, writes a
+ * variable, closes the file, then reopens it and reads the data
+ * back for verification.
+ *
+ * @author Edward Hartnett, 5/29/4
+ */
 
 #include <netcdf.h>
 #include <stdio.h>

examples/C/filter_example.c

@@ -1,22 +1,19 @@
-/*
-  Copyright 2018, UCAR/Unidata
-  See COPYRIGHT file for copying and redistribution conditions.
-*/
-/*
-This file is the same as nc_test4/test_filter.c 
-*/
-
-/*! \file
-Example program for write then read of a variable using bzip2 compression.
-
-@ingroup tutorial
-
-This is an example which 
-creates a file with a variable that is compressed using bzip2.
-Then it reads that file and verifies that it returned the correct
-uncompressed data.
-
-The meta-data (.cdl) for the created file is as follows:
+/* Copyright 2018, UCAR/Unidata.
+   See COPYRIGHT file for conditions of use. */
+/**
+ * @file
+ * @ingroup tutorial
+ * Example program for writing and reading a variable using bzip2
+ * compression.
+ *
+ * This example creates a file with a variable that is compressed
+ * using bzip2, then reads it back and verifies that the
+ * uncompressed data is correct.
+ *
+ * The meta-data (.cdl) for the created file is as follows:
+ * @author Dennis Heimbigner
+ */
+/**
 \code
 netcdf bzip2 {
 dimensions:
@@ -121,7 +118,7 @@ verifychunks(void)
     size_t chunksizes[NDIMS];
     memset(chunksizes,0,sizeof(chunksizes));
     CHECK(nc_inq_var_chunking(ncid, varid, &store, chunksizes));
-    /* Storate must be chunked, not contiguous */
+    /* Storage must be chunked, not contiguous */
     if(store != NC_CHUNKED) {
 	fprintf(stderr,"bad chunk store\n");
 	return NC_ESTORAGE;

examples/C/format.c

@@ -11,7 +11,7 @@
  * This example shows how to create and deal with files of different
  * netcdf formats (i.e. classic vs. 64-bit-offset).
  *
- * @author Ed Hartnett, 7/13/4
+ * @author Edward Hartnett, 7/13/4
  */
 
 #include <config.h>

examples/C/large_files.c

@@ -1,13 +1,14 @@
-/*! \file
-
-Copyright 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002,
-2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014,
-2015, 2016, 2017, 2018
-University Corporation for Atmospheric Research/Unidata.
-
-See \ref copyright file for more info.
-
-*/
+/* Copyright 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002,
+   2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014,
+   2015, 2016, 2017, 2018 University Corporation for Atmospheric
+   Research/Unidata.  See COPYRIGHT file for conditions of use. */
+/**
+ * @file
+ * Example of writing and reading a large netCDF file using
+ * 64-bit offset format.
+ *
+ * @author Russ Rew
+ */
 
 #include <stdio.h>
 #include <stdlib.h>

examples/C/met4D.c

@@ -1,39 +1,28 @@
-/*! \file
-
-Copyright 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002,
-2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014,
-2015, 2016, 2017, 2018
-University Corporation for Atmospheric Research/Unidata.
-
-See \ref copyright file for more info.
-
-*/
-
-/* This example program is part of Unidata's netCDF library for
-   scientific data access.
-
-   This program demonstrates various ways to create netCDF dimensions
-   and variables.
-
-   We will create a dataset with 4 variables. We'll store a 3D surface
-   temperature (lat x lon x timestep), 4D pressure (lat x lon x height x
-   timestep), a 2D initial temperature (lat x lon) and a 3D initial
-   pressure (lat x lon x height). All variables will be stored as
-   single precision floating point.
-
-   All variables are intended to share dimensions. For example, the
-   latitude axis is the same for all of them.
-
-   We'll also include the coordinate axis data for three of the four
-   dimensions, that is, labels for the lat, lon, and height axes.
-
-   Finally, we'll use some attributes to store some metadata about the
-   variables, the units. Also we'll use a file-level, or global,
-   attribute to record some information about the dataset as a whole.
-
-   Ed Hartnett, 6/3/4
-   $Id: met4D.c,v 1.1 2004/07/26 14:04:42 ed Exp $
-*/
+/* Copyright 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002,
+   2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014,
+   2015, 2016, 2017, 2018 University Corporation for Atmospheric
+   Research/Unidata.  See COPYRIGHT file for conditions of use. */
+/**
+ * @file
+ * Demonstrate creating netCDF dimensions and variables for 4D
+ * meteorological data.
+ *
+ * This example program is part of Unidata's netCDF library for
+ * scientific data access. It demonstrates various ways to create
+ * netCDF dimensions and variables.
+ *
+ * We create a dataset with 4 variables: a 3D surface temperature
+ * (lat x lon x timestep), 4D pressure (lat x lon x height x
+ * timestep), a 2D initial temperature (lat x lon), and a 3D initial
+ * pressure (lat x lon x height). All variables are stored as single
+ * precision floating point and share dimensions.
+ *
+ * We also include coordinate axis data for three of the four
+ * dimensions (lat, lon, and height), and use attributes to store
+ * units metadata and a global history attribute.
+ *
+ * @author Edward Hartnett, 6/3/4
+ */
 
 #include <netcdf.h>
 #include <stdio.h>

examples/C/parallel_vara.c

@@ -4,50 +4,46 @@
  *  See COPYRIGHT notice in top-level directory.
  *
  *********************************************************************/
-/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
- * This example shows how to use nc_put_vara_int() to write a 2D 4-byte integer
- * array in parallel and read it back using the same array partitioning pattern.
- * It first defines a netCDF variable of size global_nx * global_ny where
- *    global_ny == NY and
- *    global_nx == (NX * number of MPI processes).
- * The data partitioning pattern is a column-wise partitioning across all
- * processes. Each process writes a subarray of size ny * nx.
+/**
+ * @file
+ * Example of parallel I/O using nc_put_vara_int() and nc_get_vara_int().
  *
- *    To compile:
- *        mpicc -O2 parallel_vara.c -o parallel_vara -lnetcdf -lpnetcdf
+ * This example shows how to use nc_put_vara_int() to write a 2D
+ * 4-byte integer array in parallel and read it back using the same
+ * array partitioning pattern. It first defines a netCDF variable of
+ * size global_nx * global_ny where global_ny == NY and global_nx ==
+ * (NX * number of MPI processes). The data partitioning pattern is a
+ * column-wise partitioning across all processes. Each process writes a
+ * subarray of size ny * nx.
+ *
+ * To compile:
+ *     mpicc -O2 parallel_vara.c -o parallel_vara -lnetcdf -lpnetcdf
  *
  * Example commands for MPI run and outputs from running ncdump on the
  * NC file produced by this example program:
  *
- *    % mpiexec -n 4 ./parallel_vara /pvfs2/wkliao/testfile.nc
+ *     % mpiexec -n 4 ./parallel_vara /pvfs2/wkliao/testfile.nc
+ *
+ *     % ncdump /pvfs2/wkliao/testfile.nc
+ *     netcdf testfile {
+ *     dimensions:
+ *             y = 10 ;
+ *             x = 16 ;
+ *     variables:
+ *             int var(y, x) ;
+ *                 var:str_att_name = "example attribute of type text." ;
+ *                 var:float_att_name = 0.f, 1.f, 2.f, 3.f, 4.f, 5.f, 6.f, 7.f ;
+ *     // global attributes:
+ *                 :history = "Wed Apr 30 11:18:58 2014" ;
+ *     data:
  *
- *    % ncdump /pvfs2/wkliao/testfile.nc
- *    netcdf testfile {
- *    dimensions:
- *            y = 10 ;
- *            x = 16 ;
- *    variables:
- *            int var(y, x) ;
- *                var:str_att_name = "example attribute of type text." ;
- *                var:float_att_name = 0.f, 1.f, 2.f, 3.f, 4.f, 5.f, 6.f, 7.f ;
- *    // global attributes:
- *                :history = "Wed Apr 30 11:18:58 2014\n",
- *       "" ;
- *    data:
+ *      var =
+ *          0, 0, 0, 0, 1, 1, 1, 1, 2, 2, 2, 2, 3, 3, 3, 3,
+ *          ...
+ *     }
  *
- *     var =
- *         0, 0, 0, 0, 1, 1, 1, 1, 2, 2, 2, 2, 3, 3, 3, 3,
- *         0, 0, 0, 0, 1, 1, 1, 1, 2, 2, 2, 2, 3, 3, 3, 3,
- *         0, 0, 0, 0, 1, 1, 1, 1, 2, 2, 2, 2, 3, 3, 3, 3,
- *         0, 0, 0, 0, 1, 1, 1, 1, 2, 2, 2, 2, 3, 3, 3, 3,
- *         0, 0, 0, 0, 1, 1, 1, 1, 2, 2, 2, 2, 3, 3, 3, 3,
- *         0, 0, 0, 0, 1, 1, 1, 1, 2, 2, 2, 2, 3, 3, 3, 3,
- *         0, 0, 0, 0, 1, 1, 1, 1, 2, 2, 2, 2, 3, 3, 3, 3,
- *         0, 0, 0, 0, 1, 1, 1, 1, 2, 2, 2, 2, 3, 3, 3, 3,
- *         0, 0, 0, 0, 1, 1, 1, 1, 2, 2, 2, 2, 3, 3, 3, 3,
- *         0, 0, 0, 0, 1, 1, 1, 1, 2, 2, 2, 2, 3, 3, 3, 3 ;
- *    }
- * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
+ * @author Edward Hartnett
+ */
 
 #include <stdio.h>
 #include <stdlib.h>

examples/C/pres_temp_4D_rd.c

@@ -13,7 +13,7 @@ Research/Unidata. See COPYRIGHT file for conditions of use. */
  * This is part of the netCDF package. Full documentation of the netCDF can be found at
  * https://docs.unidata.ucar.edu/netcdf-c.
  *
- * @author Ed Hartnett
+ * @author Edward Hartnett
  */
 
 #include <stdio.h>
@@ -49,7 +49,6 @@ Research/Unidata. See COPYRIGHT file for conditions of use. */
 #define START_LON -125.0
 
 /* For the units attributes. */
-#define UNITS "units"
 #define PRES_UNITS "hPa"
 #define TEMP_UNITS "celsius"
 #define LAT_UNITS "degrees_north"

examples/C/pres_temp_4D_wr.c

@@ -3,14 +3,15 @@
 /**
  * @file
  * @defgroup tutorial Tutorial Examples
+ *
  * A more complex example of writing a netCDF file.
  *
  * This is an example program which writes some 4D pressure and
  * temperatures. It is intended to illustrate the use of the netCDF C
  * API. The companion program pres_temp_4D_rd.c shows how to read the
  * netCDF data file created by this program.
  *
- * @author Ed Hartnett
+ * @author Edward Hartnett
 */
 
 #include <stdio.h>
@@ -46,7 +47,6 @@
 #define START_LON -125.0f
 
 /* For the units attributes. */
-#define UNITS "units"
 #define PRES_UNITS "hPa"
 #define TEMP_UNITS "celsius"
 #define LAT_UNITS "degrees_north"

examples/C/quick_large_files.c

@@ -12,7 +12,7 @@
  * This program (quickly, but not thoroughly) tests the large file
  * features.
  *
- * @author Ed Hartnett, 8/11/4
+ * @author Edward Hartnett, 8/11/4
  */
 
 #include <netcdf.h>

examples/C/quick_small_files.c

@@ -17,7 +17,7 @@ info. */
  * and the offset to the beginning of this variable must be less than
  * about 2 Gbytes."
  *
- * @author Ed Hartnett
+ * @author Edward Hartnett
 */
 
 #include <netcdf.h>