Bring in better doc for time interval from ISO string.

Merge branch 'iso_time_interval_doc' into develop

Author: oehmke

src/Infrastructure/FieldBundle/src/ESMF_FieldBundle.cppF90

@@ -2183,8 +2183,8 @@ msg="This call does not work with packed FieldBundle.",&
 !------------------------------------------------------------------------------
 ^undef  ESMF_METHOD
 ^define ESMF_METHOD "ESMF_FieldBundleGetIndex()"
-!BOPI
-! !IROUTINE: ESMF_FieldBundleGet - Access the fieldIndex-th Field in FieldBundle
+!BOP
+! !IROUTINE: ESMF_FieldBundleGet - Access the Field at a specific index in a FieldBundle
 !
 ! !INTERFACE:
     ! Private name; call using ESMF_FieldBundleGet()   
@@ -2198,28 +2198,23 @@ msg="This call does not work with packed FieldBundle.",&
 type(ESMF_KeywordEnforcer), optional:: keywordEnforcer ! must use keywords below
     integer,                intent(out), optional :: rc
 !
-! TODO: This method is DEPRECATED starting at 5.2.0r (was not part of the 5.2.0r
-!       reference manual.
-! TODO: We should put a deprecation message into the Log file when this message
-!       is being called!
-!
 ! !DESCRIPTION:
-!   Get the fieldIndex-th Field in FieldBundle. The order of the Field in FieldBundle
-!   is not guranteed. If this call is used iteratively, then any Add, Replace, Remove
-!   call on the FieldBundle will invalidate the order of the Field in the FieldBundle.
+!   Get the fieldIndex-th Field from a FieldBundle. The order of the Fields in FieldBundle
+!   is not guranteed. If this call is used iteratively, then any Add, Replace, or Remove
+!   call on the FieldBundle can change the order and/or number of Fields in that FieldBundle.
 !
 !   \begin{description}
 !   \item [fieldbundle]
 !         {\tt ESMF\_FieldBundle} to be queried.
 !   \item [fieldIndex]
-!         The fieldIndex-th Field to be returned.
+!         The index of the Field to be returned.
 !   \item [field]
 !         The fieldIndex-th Field to be returned.
 !   \item [{[rc]}]
 !         Return code; equals {\tt ESMF\_SUCCESS} if there are no errors.
 !   \end{description}
 !
-!EOPI
+!EOP
 !------------------------------------------------------------------------------
     integer                       :: localrc      ! local return code
     integer                       :: l_fieldCount, i         ! helper variable

src/Infrastructure/TimeMgr/interface/ESMF_TimeInterval.F90

@@ -3135,10 +3135,12 @@ end subroutine ESMF_ParseDurString
 #undef  ESMF_METHOD
 #define ESMF_METHOD "ESMF_TimeIntervalSetStr()"
 !BOP
-! !IROUTINE: ESMF_TimeIntervalSet - Initialize or set a TimeInterval from ISO format string
+! !IROUTINE: ESMF_TimeIntervalSet - Initialize or set a TimeInterval from an ISO format string
+! \label{API:TimeIntervalSetStr}
 
 ! !INTERFACE:
-      ! Private name; call using ESMF_TimeIntervalSet()
+! Private name; call using ESMF_TimeIntervalSet()
+
       subroutine ESMF_TimeIntervalSetStr(timeinterval, timeIntervalString, rc)
 
 ! !ARGUMENTS:
@@ -3150,14 +3152,25 @@ subroutine ESMF_TimeIntervalSetStr(timeinterval, timeIntervalString, rc)
 !
 ! !DESCRIPTION:
 !     Sets the value of the {\tt ESMF\_TimeInterval} using a user specified
-!     string in ISO duration format (P[n]Y[n]M[n]DT[n]H[n]M[n]S).
+!     string in ISO duration format P[y]Y[mm]M[d]DT[h]H[m]M[s]S. See ~\cite{ISO} and ~\cite{ISOnotes} for information about the format. In ESMF's implementation the time values can have the following types: 
+!     \begin{description}
+!      \item[y] - the number of years expressed in up to a 64-bit integer
+!      \item[mm] - the number of months expressed in up to a 64-bit integer
+!      \item[d]  - the number of days expressed in up to a 64-bit integer or a 64-bit floating point value (double)
+!      \item[h] - the number of hours expressed in up to a 32-bit integer or a 64-bit floating point value (double)
+!      \item[m] - the number of minutes expressed in up to a 32-bit integer or a 64-bit floating point value (double)
+!      \item[s] - the number of seconds expressed in up to a 64-bit integer or a 64-bit floating point value (double)
+!     \end{description}
 !
+!   As with the ISO format, in ESMF's implementation the specifier and value can be left out if the value is 0. For example, P1YT1H3M4S is a valid format if the number of months and
+!   days are both 0. The time part including the T can also be left off if the time values are all 0, so P1Y is a valid string if just 1 year is being specified. 
+!      
 !     The arguments are:
 !     \begin{description}
 !     \item[timeinterval]
 !          The object instance to initialize.
 !     \item[timeIntervalString]
-!          ISO format duration string. 
+!          ISO format duration string (e.g. P[y]Y[mm]M[d]DT[h]H[m]M[s]S).
 !     \item[{[rc]}]
 !          Return code; equals {\tt ESMF\_SUCCESS} if there are no errors.
 !     \end{description}
@@ -3179,9 +3192,6 @@ subroutine ESMF_TimeIntervalSetStr(timeinterval, timeIntervalString, rc)
       if (present(rc)) rc = ESMF_RC_NOT_IMPL
       localrc = ESMF_RC_NOT_IMPL
 
-      ! DEBUG OUTPUT:
-      !write(*,*) "Duration string is:",timeIntervalString
-      
       ! Parse string into values for each time unit
       call ESMF_ParseDurString(timeintervalString, &
            yy_i8=yy_i8, mm_i8=mm_i8, d_i8=d_i8, d_r8=d_r8, &
@@ -3219,7 +3229,7 @@ end subroutine ESMF_TimeIntervalSetStr
 #undef  ESMF_METHOD
 #define ESMF_METHOD "ESMF_TimeIntervalSetStrCal()"
 !BOP
-! !IROUTINE: ESMF_TimeIntervalSet - Initialize or set a TimeInterval from ISO format string
+! !IROUTINE: ESMF_TimeIntervalSet - Initialize or set a TimeInterval from an ISO format string and calendar
 
 ! !INTERFACE:
       ! Private name; call using ESMF_TimeIntervalSet()
@@ -3235,9 +3245,12 @@ subroutine ESMF_TimeIntervalSetStrCal(timeinterval, calendar, &
 !
 !
 ! !DESCRIPTION:
-!     Sets the value of the {\tt ESMF\_TimeInterval} using a user specified
-!     string in ISO duration format (P[n]Y[n]M[n]DT[n]H[n]M[n]S).
-!
+!  Sets the value of the {\tt ESMF\_TimeInterval} using a user specified
+!  string in ISO duration format P[y]Y[mm]M[d]DT[h]H[m]M[s]S. See ~\cite{ISO} and ~\cite{ISOnotes} for
+!  information about the format. Also, see the description for the method
+! {\tt ESMF\_TimeIntervalSetStr()}~\ref{API:TimeIntervalSetStr}
+! for the specific types supported by ESMF for the values in the duration string. 
+!      
 !     The arguments are:
 !     \begin{description}
 !     \item[timeinterval]
@@ -3252,7 +3265,7 @@ subroutine ESMF_TimeIntervalSetStrCal(timeinterval, calendar, &
 !          it contains a calendar.  Alternate to, and mutually exclusive with, 
 !          calkindflag below.  Primarily for specifying a custom calendar kind.
 !     \item[timeIntervalString]
-!          ISO format duration string. 
+!          ISO format duration string (e.g. P[y]Y[mm]M[d]DT[h]H[m]M[s]S).
 !     \item[{[rc]}]
 !          Return code; equals {\tt ESMF\_SUCCESS} if there are no errors.
 !     \end{description}
@@ -3274,9 +3287,6 @@ subroutine ESMF_TimeIntervalSetStrCal(timeinterval, calendar, &
       if (present(rc)) rc = ESMF_RC_NOT_IMPL
       localrc = ESMF_RC_NOT_IMPL
 
-      ! DEBUG OUTPUT:
-      !write(*,*) "Duration string is:",timeIntervalString
-      
       ! Parse string into values for each time unit
       call ESMF_ParseDurString(timeintervalString, &
            yy_i8=yy_i8, mm_i8=mm_i8, d_i8=d_i8, d_r8=d_r8, &
@@ -3315,7 +3325,7 @@ end subroutine ESMF_TimeIntervalSetStrCal
 #undef  ESMF_METHOD
 #define ESMF_METHOD "ESMF_TimeIntervalSetStrCalTyp()"
 !BOP
-! !IROUTINE: ESMF_TimeIntervalSet - Initialize or set a TimeInterval from ISO format string
+! !IROUTINE: ESMF_TimeIntervalSet - Initialize or set a TimeInterval from an ISO format string and calendar kind
 
 ! !INTERFACE:
       ! Private name; call using ESMF_TimeIntervalSet()
@@ -3331,8 +3341,11 @@ subroutine ESMF_TimeIntervalSetStrCalTyp(timeinterval, calkindflag, &
 !
 !
 ! !DESCRIPTION:
-!     Sets the value of the {\tt ESMF\_TimeInterval} using a user specified
-!     string in ISO duration format (P[n]Y[n]M[n]DT[n]H[n]M[n]S).
+!  Sets the value of the {\tt ESMF\_TimeInterval} using a user specified
+!  string in ISO duration format P[y]Y[mm]M[d]DT[h]H[m]M[s]S. See ~\cite{ISO} and ~\cite{ISOnotes} for
+!  information about the format. Also, see the description for the method
+! {\tt ESMF\_TimeIntervalSetStr()}~\ref{API:TimeIntervalSetStr}
+! for the specific types supported by ESMF for the values in the duration string. 
 !
 !     The arguments are:
 !     \begin{description}
@@ -3343,7 +3356,7 @@ subroutine ESMF_TimeIntervalSetStrCalTyp(timeinterval, calkindflag, &
 !          calendar above.  More convenient way of specifying a built-in 
 !          calendar kind.
 !     \item[timeIntervalString]
-!          ISO format duration string. 
+!          ISO format duration string (e.g. P[y]Y[mm]M[d]DT[h]H[m]M[s]S).
 !     \item[{[rc]}]
 !          Return code; equals {\tt ESMF\_SUCCESS} if there are no errors.
 !     \end{description}
@@ -3365,10 +3378,7 @@ subroutine ESMF_TimeIntervalSetStrCalTyp(timeinterval, calkindflag, &
       if (present(rc)) rc = ESMF_RC_NOT_IMPL
       localrc = ESMF_RC_NOT_IMPL
 
-      ! DEBUG OUTPUT:
-      !write(*,*) "Duration string is:",timeIntervalString
-      
-      ! Parse string into values for each time unit
+       ! Parse string into values for each time unit
       call ESMF_ParseDurString(timeintervalString, &
            yy_i8=yy_i8, mm_i8=mm_i8, d_i8=d_i8, d_r8=d_r8, &
            h_r8=h_r8, m_r8=m_r8, s_i8=s_i8, s_r8=s_r8, rc=localrc)      
@@ -3404,7 +3414,7 @@ end subroutine ESMF_TimeIntervalSetStrCalTyp
 #undef  ESMF_METHOD
 #define ESMF_METHOD "ESMF_TimeIntervalSetStrStart()"
 !BOP
-! !IROUTINE: ESMF_TimeIntervalSet - Initialize or set a TimeInterval from ISO format string
+! !IROUTINE: ESMF_TimeIntervalSet - Initialize or set a TimeInterval from an ISO format string and start time
 
 ! !INTERFACE:
       ! Private name; call using ESMF_TimeIntervalSet()
@@ -3420,8 +3430,11 @@ subroutine ESMF_TimeIntervalSetStrStart(timeinterval, startTime, &
 !
 !
 ! !DESCRIPTION:
-!     Sets the value of the {\tt ESMF\_TimeInterval} using a user specified
-!     string in ISO duration format (P[n]Y[n]M[n]DT[n]H[n]M[n]S).
+!  Sets the value of the {\tt ESMF\_TimeInterval} using a user specified
+!  string in ISO duration format P[y]Y[mm]M[d]DT[h]H[m]M[s]S. See ~\cite{ISO} and ~\cite{ISOnotes} for
+!  information about the format. Also, see the description for the method
+! {\tt ESMF\_TimeIntervalSetStr()}~\ref{API:TimeIntervalSetStr}
+! for the specific types supported by ESMF for the values in the duration string. 
 !
 !     The arguments are:
 !     \begin{description}
@@ -3433,7 +3446,7 @@ subroutine ESMF_TimeIntervalSetStrStart(timeinterval, startTime, &
 !          in time.  If not set, and calendar also not set, calendar interval 
 !          "floats" across all calendars and times.
 !     \item[timeIntervalString]
-!          ISO format duration string. 
+!          ISO format duration string (e.g. P[y]Y[mm]M[d]DT[h]H[m]M[s]S).
 !     \item[{[rc]}]
 !          Return code; equals {\tt ESMF\_SUCCESS} if there are no errors.
 !     \end{description}
@@ -3455,9 +3468,6 @@ subroutine ESMF_TimeIntervalSetStrStart(timeinterval, startTime, &
       if (present(rc)) rc = ESMF_RC_NOT_IMPL
       localrc = ESMF_RC_NOT_IMPL
 
-      ! DEBUG OUTPUT:
-      !write(*,*) "Duration string is:",timeIntervalString
-      
       ! Parse string into values for each time unit
       call ESMF_ParseDurString(timeintervalString, &
            yy_i8=yy_i8, mm_i8=mm_i8, d_i8=d_i8, d_r8=d_r8, &