Doxygen marked source files (#600)

Add doxygen marked source

Author: MatthewMasarik-NOAA

model/src/w3metamd.F90

@@ -1,3 +1,20 @@
+!> @file
+!> @brief Dynamic storage for meta data attribute/value pairs.
+!> @author Chris Bunney @date 16-Dec-2020
+!/ ------------------------------------------------------------------- /
+!/
+!> @brief Dynamic storage for meta data attribute/value pairs.
+!>
+!> @details Provides types for handling "meta data" (attribute/value pairs)
+!>     and a linked list construct for dynamic storage.
+!>
+!> ### Change log
+!>   Date      | Ver  | Comments  
+!> ------------|------|---------
+!> 16-Dec-2020 | 7.12 | Creation 
+!>
+!> @author Chris Bunney @date 16-Dec-2020
+!>
 !/ ------------------------------------------------------------------- /
       MODULE W3METAMD
 !/
@@ -17,39 +34,45 @@ MODULE W3METAMD
 !     and a linked list construct for dynamic storage.
 !/ ------------------------------------------------------------------- /
 
-      ! Values to represent "unset" data:
+      !> Value to represent "unset" character variable
       CHARACTER(LEN=*), PARAMETER :: UNSETC = "unset"
+      !> Value to represent "unset" real variable
       REAL, PARAMETER             :: UNSETR = HUGE(1.0)
 
-      ! Type for storing a user defined metadata pair:
+      !> Type for storing a user defined metadata pair as linked list element
       TYPE META_PAIR_T
-        CHARACTER(LEN=64)  :: ATTNAME = UNSETC
-        CHARACTER(LEN=120) :: ATTVAL = UNSETC
-        CHARACTER          :: TYPE = 'c'    ! c,i,f/r
-        TYPE(META_PAIR_T), POINTER  :: NEXT
+        CHARACTER(LEN=64)  :: ATTNAME = UNSETC  !< Attribute name
+        CHARACTER(LEN=120) :: ATTVAL = UNSETC   !< Attribute value
+        CHARACTER          :: TYPE = 'c'        !< Attribute type (c,i,f/r)
+        TYPE(META_PAIR_T), POINTER  :: NEXT     !< Pointer to next node
       END TYPE META_PAIR_T
 
+      !> Linked list of meta data pairs
       TYPE META_LIST_T
         TYPE (META_PAIR_T), POINTER :: HEAD => NULL(), TAIL => NULL()
-        INTEGER                     :: N = 0
+        INTEGER                     :: N = 0    !< Num elements in list
       END TYPE META_LIST_T
 
-      ! Interface to facilitate adding real/int/character values to list
+      !> Interface to facilitate adding real/int/character values to list
       INTERFACE META_LIST_APPEND
-        MODULE PROCEDURE META_LIST_APPEND_M
-        MODULE PROCEDURE META_LIST_APPEND_R
-        MODULE PROCEDURE META_LIST_APPEND_I
-        MODULE PROCEDURE META_LIST_APPEND_C
+        MODULE PROCEDURE META_LIST_APPEND_M !< Append a META_PAIR_T
+        MODULE PROCEDURE META_LIST_APPEND_R !< Append a REAL value
+        MODULE PROCEDURE META_LIST_APPEND_I !< Append an INTEGER value
+        MODULE PROCEDURE META_LIST_APPEND_C !< Append a CHARACTER value
       END INTERFACE META_LIST_APPEND
 
-
       CONTAINS
 
 
 !/ ------------------------------------------------------------------- /
-      SUBROUTINE DEL_META_LIST(LIST)
-!     Deletes all entries in list
+!> @brief Deletes all entries in list.
+!>
+!> @param[in,out] LIST The list to clear.
+!>
+!> @author Chris Bunney
 !/ ------------------------------------------------------------------- /
+      SUBROUTINE DEL_META_LIST(LIST)
+
       IMPLICIT NONE
 
       TYPE(META_LIST_T), INTENT(INOUT) :: LIST
@@ -76,9 +99,21 @@ END SUBROUTINE DEL_META_LIST
 
 
 !/ ------------------------------------------------------------------- /
-      FUNCTION COPY_META_LIST(LIST) RESULT(COPY)
-!     Create a deep copy of a meta data list
+!> @brief Create a deep copy of a meta data list
+!>
+!> @details A "deep copy" ensures that a copy is made of the underlying
+!>    linked list, rather than a simply copy of the pointers to the
+!>    existing list.
+!>
+!> @param[in] LIST The list to copy
+!>
+!> @returns A new META_LIST_T
+!>
+!> @author Chris Bunney
+!>
 !/ ------------------------------------------------------------------- /
+      FUNCTION COPY_META_LIST(LIST) RESULT(COPY)
+
       IMPLICIT NONE
 
       TYPE(META_LIST_T), INTENT(IN) :: LIST
@@ -105,9 +140,14 @@ END FUNCTION COPY_META_LIST
 
 
 !/ ------------------------------------------------------------------- /
-      SUBROUTINE PRINT_META_LIST(LIST)
-!     Prints meta pairs in list to screen
+!> @brief Prints meta pairs in list to screen
+!>
+!> @param[in] LIST  Linked list of meta data to print
+!>
+!> @author Chris Bunney
 !/ ------------------------------------------------------------------- /
+      SUBROUTINE PRINT_META_LIST(LIST)
+
       IMPLICIT NONE
 
       TYPE(META_LIST_T), INTENT(IN) :: LIST
@@ -133,9 +173,15 @@ END SUBROUTINE PRINT_META_LIST
 
 
 !/ ------------------------------------------------------------------- /
-      SUBROUTINE META_LIST_APPEND_M(LIST, META)
-!     Append META_PAIR_T object to list
+!> @brief Append META_PAIR_T object to list
+!>
+!> @param[in,out] LIST  The list to append to
+!> @param[in]     META  The META_PAIR_T object to append.
+!>
+!> @author Chris Bunney
 !/ ------------------------------------------------------------------- /
+      SUBROUTINE META_LIST_APPEND_M(LIST, META)
+
       IMPLICIT NONE
 
       TYPE(META_LIST_T), INTENT(INOUT) :: LIST
@@ -168,9 +214,16 @@ END SUBROUTINE META_LIST_APPEND_M
 
 
 !/ ------------------------------------------------------------------- /
-      SUBROUTINE META_LIST_APPEND_R(LIST, ATTNAME, RVAL)
-!     Append real value meta pair to list
+!> @brief Append REAL value attribute to list
+!>
+!> @param[in,out] LIST     The list to append to
+!> @param[in]     ATTNAME  The attribute name
+!> @param[in]     RVAL     The attribute value (REAL)
+!>
+!> @author Chris Bunney
 !/ ------------------------------------------------------------------- /
+      SUBROUTINE META_LIST_APPEND_R(LIST, ATTNAME, RVAL)
+
       IMPLICIT NONE
 
       TYPE(META_LIST_T), INTENT(INOUT) :: LIST
@@ -190,9 +243,16 @@ END SUBROUTINE META_LIST_APPEND_R
 
 
 !/ ------------------------------------------------------------------- /
-      SUBROUTINE META_LIST_APPEND_I(LIST, ATTNAME, IVAL)
-!     Append integer value meta pair to list
+!> @brief Append INTEGER value attribute to list
+!>
+!> @param[in,out] LIST     The list to append to
+!> @param[in]     ATTNAME  The attribute name
+!> @param[in]     IVAL     The attribute value (INTEGER)
+!>
+!> @author Chris Bunney
 !/ ------------------------------------------------------------------- /
+      SUBROUTINE META_LIST_APPEND_I(LIST, ATTNAME, IVAL)
+
       IMPLICIT NONE
 
       TYPE(META_LIST_T), INTENT(INOUT) :: LIST
@@ -212,9 +272,16 @@ END SUBROUTINE META_LIST_APPEND_I
 
 
 !/ ------------------------------------------------------------------- /
-      SUBROUTINE META_LIST_APPEND_C(LIST, ATTNAME, SVAL)
-!     Append character value meta pair to list
+!> @brief Append CHARACTER string value attribute to list
+!>
+!> @param[in,out] LIST     The list to append to
+!> @param[in]     ATTNAME  The attribute name
+!> @param[in]     SVAL     The attribute value (CHARACTER string)
+!>
+!> @author Chris Bunney
 !/ ------------------------------------------------------------------- /
+      SUBROUTINE META_LIST_APPEND_C(LIST, ATTNAME, SVAL)
+
       IMPLICIT NONE
 
       TYPE(META_LIST_T), INTENT(INOUT) :: LIST
@@ -231,13 +298,18 @@ SUBROUTINE META_LIST_APPEND_C(LIST, ATTNAME, SVAL)
 
       END SUBROUTINE META_LIST_APPEND_C
 
-!     Append pair to list
-
 
 !/ ------------------------------------------------------------------- /
-      SUBROUTINE META_LIST_FIND_ATTR(LIST, ATTN, META, ERR)
-!     Find (first) entry in list with matching attname
+!> @brief Find (first) entry in list with matching attname
+!>
+!> @param[in]   LIST   List to search
+!> @param[in]   ATTN   Attribute name to search for
+!> @param[out]  META   Meta data type to store matched result in
+!> @param[out]  ERR    Error status (0=Found, 1=Empty list, 2=Not found)
+!>
+!> @author Chris Bunney
 !/ ------------------------------------------------------------------- /
+      SUBROUTINE META_LIST_FIND_ATTR(LIST, ATTN, META, ERR)
       IMPLICIT NONE
 
       TYPE(META_LIST_T), INTENT(IN)           :: LIST
@@ -269,9 +341,17 @@ END SUBROUTINE META_LIST_FIND_ATTR
 
 
 !/ ------------------------------------------------------------------- /
-      FUNCTION META_LIST_HAS_ATTR(LIST, ATTN) RESULT(FOUND)
-!     Tests whether list contains an entry with specified attname
+!> @brief Tests whether list contains an entry with specified attname
+!>
+!> @param[in]  LIST  The list to search
+!> @param[in]  ATTN  Attribute name to search for
+!>
+!> @returns LOGICAL: True if match found, False otherwise.
+!>
+!> @author Chris Bunney
 !/ ------------------------------------------------------------------- /
+      FUNCTION META_LIST_HAS_ATTR(LIST, ATTN) RESULT(FOUND)
+
       IMPLICIT NONE
 
       TYPE(META_LIST_T), INTENT(IN)           :: LIST