Add basic doxygen to remaining repository routines

Add basic doxygen to all files under 'fre-nctools.fd' and 'orog.fd'.

Removed unused include file - resovod.h - from orog.fd and converted
machine.h to a Fortran module.   Doxygen works better with
module files. 

Update Doxyfile.in to use full paths for better online display.

Issue ufs-community#191.

docs/Doxyfile.in

@@ -130,7 +130,7 @@ INLINE_INHERITED_MEMB  = YES
 # shortest path that makes the file name unique will be used
 # The default value is: YES.
 
-FULL_PATH_NAMES        = NO
+FULL_PATH_NAMES        = YES
 
 # The STRIP_FROM_PATH tag can be used to strip a user-defined part of the path.
 # Stripping is only done if one of the specified strings matches the left-hand

sorc/fre-nctools.fd/shared_lib/affinity.c

@@ -1,4 +1,6 @@
-/** @file */
+/** @file 
+    @brief Set or get CPU affinity.
+*/
 #define _GNU_SOURCE
 
 #include <stdio.h>

sorc/fre-nctools.fd/shared_lib/constant.h

@@ -1,3 +1,5 @@
-/** @file */
+/** @file 
+    @brief Set some global constants.
+*/
 #define RADIUS        (6371000.)
 #define STRING        255

sorc/fre-nctools.fd/shared_lib/create_xgrid.c

@@ -1,4 +1,6 @@
-/** @file */
+/** @file
+    @brief Utility routines to create and process exchange grids.
+*/
 #include <stdlib.h>
 #include <stdio.h>
 #include <math.h>

sorc/fre-nctools.fd/shared_lib/create_xgrid.h

@@ -1,4 +1,6 @@
-/** @file */
+/** @file
+    @brief Function declarations for create_xgrid.c.
+*/
 #ifndef CREATE_XGRID_H_
 #define CREATE_XGRID_H_
 #ifndef MAXXGRID

sorc/fre-nctools.fd/shared_lib/gradient.F90

@@ -1,3 +1,8 @@
+!> @file
+!!
+!! @brief Utility routines to calculate gradient.
+!!
+!! @author Zhi.Liang@noaa.gov
 module gradient_mod
 ! <CONTACT EMAIL="Zhi.Liang@noaa.gov">
 !   Zhi Liang

sorc/fre-nctools.fd/shared_lib/gradient_c2l.c

@@ -1,4 +1,6 @@
-/** @file */
+/** @file
+    @brief Compute gradient terms.
+*/
 #include <math.h>
 #include <stdlib.h>
 #include "constant.h"

sorc/fre-nctools.fd/shared_lib/gradient_c2l.h

@@ -1,4 +1,6 @@
-/** @file */
+/** @file 
+    @brief Function declarations for gradient_c2l.c
+*/
 #ifndef GRADIENT_H_
 #define GRADIENT_H_
 void grad_c2l(const int *nlon, const int *nlat, const double *pin, const double *dx, const double *dy, const double *area,

sorc/fre-nctools.fd/shared_lib/grid.F90

@@ -1,3 +1,6 @@
+!> @file
+!! @brief Utility routines to compute grid parameters such as size and area.
+!!
 module grid_mod
 
 use mpp_mod, only : mpp_root_pe

sorc/fre-nctools.fd/shared_lib/interp.c

@@ -1,8 +1,5 @@
-/** @file */
-/*
-  Copyright 2011 NOAA Geophysical Fluid Dynamics Lab, Princeton, NJ
-  This program is distributed under the terms of the GNU General Public
-  License. See the file COPYING contained in this directory
+/** @file 
+    @brief Interpolation utilities.
 */
 #include <stdio.h>
 #include <stdlib.h>

sorc/fre-nctools.fd/shared_lib/interp.h

@@ -1,16 +1,9 @@
-/** @file */
-/*
-  Copyright 2011 NOAA Geophysical Fluid Dynamics Lab, Princeton, NJ
-  This program is distributed under the terms of the GNU General Public
-  License. See the file COPYING contained in this directory
+/** @file
+    @brief Function declarations for interp.c
+    @author Zhi.Liang@noaa.gov
 */
 #ifndef INTERP_H_
 #define INTERP_H_
-/*********************************************************************
-                     interp.h
-   This header files contains defition of some interpolation routine  (1-D or 2-D).
-   contact: Zhi.Liang@noaa.gov
-*********************************************************************/
 void cubic_spline_sp(int size1, int size2, const double *grid1, const double *grid2, const double *data1,
                   double *data2 );
 void cubic_spline(int size1, int size2, const double *grid1, const double *grid2, const double *data1,

sorc/fre-nctools.fd/shared_lib/mosaic.F90

@@ -1,3 +1,7 @@
+!> @file
+!! @brief Read information from the mosaic file.
+!! @author Zhi.Liang@noaa.gov
+!!
 module mosaic_mod
 
 ! <CONTACT EMAIL="Zhi.Liang@noaa.gov">

sorc/fre-nctools.fd/shared_lib/mosaic_util.c

@@ -1,4 +1,6 @@
-/** @file */
+/** @file 
+    @brief Compute various grid statistics. 
+*/
 #include <stdlib.h>
 #include <stdio.h>
 #include <math.h>

sorc/fre-nctools.fd/shared_lib/mosaic_util.h

@@ -1,10 +1,7 @@
-/** @file */
-/***********************************************************************
-                      mosaic_util.h
-    This header file provide some utilities routine that will be used in many tools.
-    
-    contact: Zhi.Liang@noaa.gov
-***********************************************************************/
+/** @file
+    @brief Function declarations for mosaic_util.c.
+    @author Zhi.Liang@noaa.gov
+*/
 #ifndef MOSAIC_UTIL_H_
 #define MOSAIC_UTIL_H_
 

sorc/fre-nctools.fd/shared_lib/mpp.c

@@ -1,4 +1,6 @@
-/** @file */
+/** @file
+    @brief MPI utility routines 
+*/
 #include <stdlib.h>
 #include <stdio.h>
 #include <string.h>

sorc/fre-nctools.fd/shared_lib/mpp.h

@@ -1,11 +1,10 @@
-/** @file */
+/** @file
 
-/*********************************************************************
-                    mpp.h
-  This header contains subroutine for parallel programming.
-  only MPI parallel is implemented. 
-  Contact: Zhi.Liang@noaa.gov
- ********************************************************************/
+  @brief Function declarations for parallel programming. Only
+  MPI parallel is implemented. 
+
+  @author Zhi.Liang@noaa.gov
+*/
 #ifndef MPP_H_
 #define MPP_H_
 

sorc/fre-nctools.fd/shared_lib/mpp_domain.c

@@ -1,10 +1,8 @@
-/** @file */
-/*
-      **** MppDomain.cpp ****
-      MppDomain package
-      NOTE: only mpi is implemented here. if needed, shmem version
-      will be added on in the future.
-      Contact: Zhi.Liang@noaa.gov
+/** @file
+    @brief MppDomain package
+    @note Only mpi is implemented here. If needed, shmem version
+    will be added on in the future.
+    @author Zhi.Liang@noaa.gov
 */
 #include <stdlib.h>
 #include <math.h>

sorc/fre-nctools.fd/shared_lib/mpp_domain.h

@@ -1,14 +1,15 @@
-/** @file */
-/****************************************************************
-                        mpp_domain.h 
-   This headers define interface to define domain layout, 
-   define domain decomposition and global field to root pe, 
-   some utilities routine to return domain decomposition.
-   Currently it only used in tools and assume only one domain is created. 
-   If more domains are needed, we may define a struct to hold domain informaiton.
-   contact: Zhi.Liang@noaa.gov
+/** @file
+  
+    @brief Headers that define interface, domain layout, 
+    domain decomposition and global field to root pe.
+    Some routines return domain decomposition.
 
-****************************************************************/
+    @note Currently it only used in tools and assumes only one domain is created. 
+    If more domains are needed, we may define a struct to hold domain informaiton.
+
+    @author Zhi.Liang@noaa.gov
+
+*/
 #ifndef MPP_DOMAIN_H_
 #define MPP_DOMAIN_H_
 #define max(a,b) (a>b ? a:b)

sorc/fre-nctools.fd/shared_lib/mpp_io.c

@@ -1,4 +1,7 @@
-/** @file */
+/** @file
+    @brief Utility routines to read/write netcdf.
+    @author Zhi.Liang@noaa.gov
+*/
 #include <stdlib.h>
 #include <stdio.h>
 #include <string.h>

sorc/fre-nctools.fd/shared_lib/mpp_io.h

@@ -1,12 +1,7 @@
-/** @file */
-/****************************************************************
-                    mpp_io.h
-   This headers defines interface to read and write netcdf file. All the data
-will be written out from root pe. 
-
-   contact: Zhi.Liang@noaa.gov
-
-****************************************************************/
+/** @file 
+    @brief Define constants and function declarations for mpp_io.c
+    @author Zhi.Liang@noaa.gov
+*/
 #ifndef MPP_IO_H_
 #define MPP_IO_H_
 #include <netcdf.h>

sorc/fre-nctools.fd/shared_lib/read_mosaic.c

@@ -1,4 +1,6 @@
-/** @file */
+/** @file 
+    @brief Utilities to read the mosaic file.
+*/
 #include <stdlib.h>
 #include <stdio.h>
 #include <math.h>

sorc/fre-nctools.fd/shared_lib/read_mosaic.h

@@ -1,4 +1,6 @@
-/** @file */
+/** @file
+    @brief Function declarations for read_mosaic.c 
+*/
 #ifndef READ_MOSAIC_H_
 #define READ_MOSAIC_H_
 

sorc/fre-nctools.fd/shared_lib/tool_util.c

@@ -1,4 +1,7 @@
-/** @file */
+/** @file
+    @brief Utility routines used by many tools.
+    @author Zhi.Liang@noaa.gov
+*/
 #include <stdlib.h> 
 #include <stdio.h>
 #include <string.h>

sorc/fre-nctools.fd/shared_lib/tool_util.h

@@ -1,6 +1,5 @@
 /** @file 
-    This header file provide some utilities routine that will be used in many tools.
-    
+    @brief Function declarations for tool_util.c
     @author Zhi.Liang@noaa.gov
 */
 #ifndef TOOL_UTIL_H_

sorc/fre-nctools.fd/tools/fregrid/bilinear_interp.c

@@ -1,3 +1,6 @@
+/** @file
+    @brief Routines to perform bilinear interpolation.
+*/
 #include <stdlib.h>
 #include <stdio.h>
 #include <math.h>

sorc/fre-nctools.fd/tools/fregrid/bilinear_interp.h

@@ -1,3 +1,6 @@
+/** @file 
+    @brief Function declarations for bilinear interpolation module.
+*/
 #ifndef BILINEAR_INTERP_H_
 #define BILINEAR_INTERP_H_
 void setup_bilinear_interp(int ntiles_in, const Grid_config *grid_in, int ntiles_out, const Grid_config *grid_out, 

sorc/fre-nctools.fd/tools/fregrid/conserve_interp.c

@@ -1,3 +1,6 @@
+/** @file 
+    @brief Routines to perform conservative interpolation.
+*/
 #include <stdlib.h>
 #include <stdio.h>
 #include <string.h>

sorc/fre-nctools.fd/tools/fregrid/conserve_interp.h

@@ -1,3 +1,6 @@
+/** @file 
+    @brief Function declarations for conservative interpolation module.
+*/
 #ifndef CONSERVE_INTERP_H_
 #define CONSERVE_INTERP_H_
 #include "globals.h"

sorc/fre-nctools.fd/tools/fregrid/fregrid.c

@@ -1,24 +1,10 @@
-/*
-  This program remaps (scalar or vector) data from the input grid
+/** @file
+  
+  @brief This program remaps (scalar or vector) data from the input grid
   to the output grid
 
- AUTHOR: Zhi Liang (Zhi.Liang@noaa.gov)
+  @author Zhi Liang (Zhi.Liang@noaa.gov)
           NOAA Geophysical Fluid Dynamics Lab, Princeton, NJ
- 
-  This program is free software; you can redistribute it and/or modify
-  it under the terms of the GNU General Public License as published by
-  the Free Software Foundation; either version 2 of the License, or
-  (at your option) any later version.
- 
-  This program is distributed in the hope that it will be useful,
-  but WITHOUT ANY WARRANTY; without even the implied warranty of
-  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-  GNU General Public License for more details.
- 
-  For the full text of the GNU General Public License,
-  write to: Free Software Foundation, Inc.,
-            675 Mass Ave, Cambridge, MA 02139, USA.  
------------------------------------------------------------------------
 */
 #include <stdlib.h>
 #include <stdio.h>

sorc/fre-nctools.fd/tools/fregrid/fregrid_util.c

@@ -1,3 +1,6 @@
+/** @file 
+    @brief Utilities for the fregrid program.
+*/
 #include <stdlib.h>
 #include <stdio.h>
 #include <math.h>

sorc/fre-nctools.fd/tools/fregrid/fregrid_util.h

@@ -1,3 +1,6 @@
+/** @file
+    @brief Function declarations for the fregrid utility module.
+*/
 #ifndef FREGRID_UTIL_H_
 #define FREGRID_UTIL_H_
 #include "globals.h"

sorc/fre-nctools.fd/tools/fregrid/globals.h

@@ -1,3 +1,6 @@
+/** @file
+    @brief Define global constants and type definitions.
+*/
 #ifndef GLOBALS_H_
 #define GLOBALS_H_
 #include <netcdf.h>

sorc/fre-nctools.fd/tools/make_hgrid/create_conformal_cubic_grid.c

@@ -1,3 +1,6 @@
+/** @file
+    @brief Create conformal cubic grids.
+*/
 #include <stdlib.h>
 #include <stdio.h>
 #include <complex.h>

sorc/fre-nctools.fd/tools/make_hgrid/create_gnomonic_cubic_grid.c

@@ -1,3 +1,6 @@
+/** @file
+    @brief Create gnomonic cubic grids.
+*/
 #include <stdlib.h>
 #include <stdio.h>
 #include <string.h>

sorc/fre-nctools.fd/tools/make_hgrid/create_grid_from_file.c

@@ -1,7 +1,5 @@
-/*
-  Copyright 2011 NOAA Geophysical Fluid Dynamics Lab, Princeton, NJ
-  This program is distributed under the terms of the GNU General Public
-  License. See the file COPYING contained in this directory
+/** @file
+    @brief Create grid from a file.
 */
 #include <stdlib.h>
 #include <stdio.h>

sorc/fre-nctools.fd/tools/make_hgrid/create_hgrid.h

@@ -1,12 +1,12 @@
-/*******************************************************************************
-                             create_hgrid.h
+/** @file
+  
   This header file provide interface to create different types of horizontal 
-  grid. geographical grid location, cell length, cell area and rotation
+  grid. Geographical grid location, cell length, cell area and rotation
   angle are returned. All the returned data are on supergrid.
 
-  contact: Zhi.Liang@noaa.gov
+  @author Zhi.Liang@noaa.gov
 
-*******************************************************************************/
+*/
 #ifndef CREATE_HGRID_H_
 #define CREATE_HGRID_H_
 void create_regular_lonlat_grid( int *nxbnds, int *nybnds, double *xbnds, double *ybnds,

sorc/fre-nctools.fd/tools/make_hgrid/create_lonlat_grid.c

@@ -1,3 +1,7 @@
+/** @file 
+    @brief Routines to create regular lat/lon, spectral, tripolar
+    and f-plane grids.
+*/ 
 #include <stdlib.h>
 #include <stdio.h>
 #include <complex.h>