diff --git a/src/framework/MOM_document.F90 b/src/framework/MOM_document.F90 index a61c20cf5a..144e10c15d 100644 --- a/src/framework/MOM_document.F90 +++ b/src/framework/MOM_document.F90 @@ -28,6 +28,7 @@ module MOM_document integer, parameter :: mLen = 1240 ! Length of interface/message strings +!> A structure that controls where the documentation occurs, its veborsity and formatting. type, public :: doc_type ; private integer :: unitAll = -1 ! The open unit number for docFileBase + .all. integer :: unitShort = -1 ! The open unit number for docFileBase + .short. @@ -60,9 +61,13 @@ module MOM_document ! ---------------------------------------------------------------------- +!> This subroutine handles parameter documentation with no value. subroutine doc_param_none(doc, varname, desc, units) - type(doc_type), pointer :: doc - character(len=*), intent(in) :: varname, desc, units + type(doc_type), pointer :: doc !< A pointer to a structure that controls where the + !! documentation occurs and its formatting + character(len=*), intent(in) :: varname !< The name of the parameter being documented + character(len=*), intent(in) :: desc !< A description of the parameter being documented + character(len=*), intent(in) :: units !< The units of the parameter being documented ! This subroutine handles parameter documentation with no value. integer :: numspc character(len=mLen) :: mesg @@ -80,14 +85,18 @@ subroutine doc_param_none(doc, varname, desc, units) endif end subroutine doc_param_none +!> This subroutine handles parameter documentation for logicals. subroutine doc_param_logical(doc, varname, desc, units, val, default, & layoutParam, debuggingParam) - type(doc_type), pointer :: doc - character(len=*), intent(in) :: varname, desc, units - logical, intent(in) :: val - logical, optional, intent(in) :: default - logical, optional, intent(in) :: layoutParam - logical, optional, intent(in) :: debuggingParam + type(doc_type), pointer :: doc !< A pointer to a structure that controls where the + !! documentation occurs and its formatting + character(len=*), intent(in) :: varname !< The name of the parameter being documented + character(len=*), intent(in) :: desc !< A description of the parameter being documented + character(len=*), intent(in) :: units !< The units of the parameter being documented + logical, intent(in) :: val !< The value of this parameter + logical, optional, intent(in) :: default !< The default value of this parameter + logical, optional, intent(in) :: layoutParam !< If present and true, this is a layout parameter. + logical, optional, intent(in) :: debuggingParam !< If present and true, this is a debugging parameter. ! This subroutine handles parameter documentation for logicals. character(len=mLen) :: mesg logical :: equalsDefault @@ -118,14 +127,18 @@ subroutine doc_param_logical(doc, varname, desc, units, val, default, & endif end subroutine doc_param_logical +!> This subroutine handles parameter documentation for arrays of logicals. subroutine doc_param_logical_array(doc, varname, desc, units, vals, default, & layoutParam, debuggingParam) - type(doc_type), pointer :: doc - character(len=*), intent(in) :: varname, desc, units - logical, intent(in) :: vals(:) - logical, optional, intent(in) :: default - logical, optional, intent(in) :: layoutParam - logical, optional, intent(in) :: debuggingParam + type(doc_type), pointer :: doc !< A pointer to a structure that controls where the + !! documentation occurs and its formatting + character(len=*), intent(in) :: varname !< The name of the parameter being documented + character(len=*), intent(in) :: desc !< A description of the parameter being documented + character(len=*), intent(in) :: units !< The units of the parameter being documented + logical, intent(in) :: vals(:) !< The array of values to record + logical, optional, intent(in) :: default !< The default value of this parameter + logical, optional, intent(in) :: layoutParam !< If present and true, this is a layout parameter. + logical, optional, intent(in) :: debuggingParam !< If present and true, this is a debugging parameter. ! This subroutine handles parameter documentation for arrays of logicals. integer :: i character(len=mLen) :: mesg @@ -164,14 +177,18 @@ subroutine doc_param_logical_array(doc, varname, desc, units, vals, default, & endif end subroutine doc_param_logical_array +!> This subroutine handles parameter documentation for integers. subroutine doc_param_int(doc, varname, desc, units, val, default, & layoutParam, debuggingParam) - type(doc_type), pointer :: doc - character(len=*), intent(in) :: varname, desc, units - integer, intent(in) :: val - integer, optional, intent(in) :: default - logical, optional, intent(in) :: layoutParam - logical, optional, intent(in) :: debuggingParam + type(doc_type), pointer :: doc !< A pointer to a structure that controls where the + !! documentation occurs and its formatting + character(len=*), intent(in) :: varname !< The name of the parameter being documented + character(len=*), intent(in) :: desc !< A description of the parameter being documented + character(len=*), intent(in) :: units !< The units of the parameter being documented + integer, intent(in) :: val !< The value of this parameter + integer, optional, intent(in) :: default !< The default value of this parameter + logical, optional, intent(in) :: layoutParam !< If present and true, this is a layout parameter. + logical, optional, intent(in) :: debuggingParam !< If present and true, this is a debugging parameter. ! This subroutine handles parameter documentation for integers. character(len=mLen) :: mesg character(len=doc%commentColumn) :: valstring @@ -196,14 +213,18 @@ subroutine doc_param_int(doc, varname, desc, units, val, default, & endif end subroutine doc_param_int +!> This subroutine handles parameter documentation for arrays of integers. subroutine doc_param_int_array(doc, varname, desc, units, vals, default, & layoutParam, debuggingParam) - type(doc_type), pointer :: doc - character(len=*), intent(in) :: varname, desc, units - integer, intent(in) :: vals(:) - integer, optional, intent(in) :: default - logical, optional, intent(in) :: layoutParam - logical, optional, intent(in) :: debuggingParam + type(doc_type), pointer :: doc !< A pointer to a structure that controls where the + !! documentation occurs and its formatting + character(len=*), intent(in) :: varname !< The name of the parameter being documented + character(len=*), intent(in) :: desc !< A description of the parameter being documented + character(len=*), intent(in) :: units !< The units of the parameter being documented + integer, intent(in) :: vals(:) !< The array of values to record + integer, optional, intent(in) :: default !< The default value of this parameter + logical, optional, intent(in) :: layoutParam !< If present and true, this is a layout parameter. + logical, optional, intent(in) :: debuggingParam !< If present and true, this is a debugging parameter. ! This subroutine handles parameter documentation for arrays of integers. integer :: i character(len=mLen) :: mesg @@ -235,12 +256,16 @@ subroutine doc_param_int_array(doc, varname, desc, units, vals, default, & end subroutine doc_param_int_array +!> This subroutine handles parameter documentation for reals. subroutine doc_param_real(doc, varname, desc, units, val, default, debuggingParam) - type(doc_type), pointer :: doc - character(len=*), intent(in) :: varname, desc, units - real, intent(in) :: val - real, optional, intent(in) :: default - logical, optional, intent(in) :: debuggingParam + type(doc_type), pointer :: doc !< A pointer to a structure that controls where the + !! documentation occurs and its formatting + character(len=*), intent(in) :: varname !< The name of the parameter being documented + character(len=*), intent(in) :: desc !< A description of the parameter being documented + character(len=*), intent(in) :: units !< The units of the parameter being documented + real, intent(in) :: val !< The value of this parameter + real, optional, intent(in) :: default !< The default value of this parameter + logical, optional, intent(in) :: debuggingParam !< If present and true, this is a debugging parameter. ! This subroutine handles parameter documentation for reals. character(len=mLen) :: mesg character(len=doc%commentColumn) :: valstring @@ -265,12 +290,16 @@ subroutine doc_param_real(doc, varname, desc, units, val, default, debuggingPara endif end subroutine doc_param_real +!> This subroutine handles parameter documentation for arrays of reals. subroutine doc_param_real_array(doc, varname, desc, units, vals, default, debuggingParam) - type(doc_type), pointer :: doc - character(len=*), intent(in) :: varname, desc, units - real, intent(in) :: vals(:) - real, optional, intent(in) :: default - logical, optional, intent(in) :: debuggingParam + type(doc_type), pointer :: doc !< A pointer to a structure that controls where the + !! documentation occurs and its formatting + character(len=*), intent(in) :: varname !< The name of the parameter being documented + character(len=*), intent(in) :: desc !< A description of the parameter being documented + character(len=*), intent(in) :: units !< The units of the parameter being documented + real, intent(in) :: vals(:) !< The array of values to record + real, optional, intent(in) :: default !< The default value of this parameter + logical, optional, intent(in) :: debuggingParam !< If present and true, this is a debugging parameter. ! This subroutine handles parameter documentation for arrays of reals. integer :: i character(len=mLen) :: mesg @@ -299,14 +328,19 @@ subroutine doc_param_real_array(doc, varname, desc, units, vals, default, debugg end subroutine doc_param_real_array +!> This subroutine handles parameter documentation for character strings. subroutine doc_param_char(doc, varname, desc, units, val, default, & layoutParam, debuggingParam) - type(doc_type), pointer :: doc - character(len=*), intent(in) :: varname, desc, units - character(len=*), intent(in) :: val - character(len=*), optional, intent(in) :: default - logical, optional, intent(in) :: layoutParam - logical, optional, intent(in) :: debuggingParam + type(doc_type), pointer :: doc !< A pointer to a structure that controls where the + !! documentation occurs and its formatting + character(len=*), intent(in) :: varname !< The name of the parameter being documented + character(len=*), intent(in) :: desc !< A description of the parameter being documented + character(len=*), intent(in) :: units !< The units of the parameter being documented + character(len=*), intent(in) :: val !< The value of the parameter + character(len=*), & + optional, intent(in) :: default !< The default value of this parameter + logical, optional, intent(in) :: layoutParam !< If present and true, this is a layout parameter. + logical, optional, intent(in) :: debuggingParam !< If present and true, this is a debugging parameter. ! This subroutine handles parameter documentation for character strings. character(len=mLen) :: mesg logical :: equalsDefault @@ -330,10 +364,12 @@ subroutine doc_param_char(doc, varname, desc, units, val, default, & end subroutine doc_param_char +!> This subroutine handles documentation for opening a parameter block. subroutine doc_openBlock(doc, blockName, desc) - type(doc_type), pointer :: doc - character(len=*), intent(in) :: blockName - character(len=*), optional, intent(in) :: desc + type(doc_type), pointer :: doc !< A pointer to a structure that controls where the + !! documentation occurs and its formatting + character(len=*), intent(in) :: blockName !< The name of the parameter block being opened + character(len=*), optional, intent(in) :: desc !< A description of the parameter block being opened ! This subroutine handles documentation for opening a parameter block. character(len=mLen) :: mesg character(len=doc%commentColumn) :: valstring @@ -353,9 +389,11 @@ subroutine doc_openBlock(doc, blockName, desc) doc%blockPrefix = trim(doc%blockPrefix)//trim(blockName)//'%' end subroutine doc_openBlock +!> This subroutine handles documentation for closing a parameter block. subroutine doc_closeBlock(doc, blockName) - type(doc_type), pointer :: doc - character(len=*), intent(in) :: blockName + type(doc_type), pointer :: doc !< A pointer to a structure that controls where the + !! documentation occurs and its formatting + character(len=*), intent(in) :: blockName !< The name of the parameter block being closed ! This subroutine handles documentation for closing a parameter block. character(len=mLen) :: mesg character(len=doc%commentColumn) :: valstring @@ -377,14 +415,18 @@ subroutine doc_closeBlock(doc, blockName) endif end subroutine doc_closeBlock +!> This subroutine handles parameter documentation for time-type variables. subroutine doc_param_time(doc, varname, desc, units, val, default, & layoutParam, debuggingParam) - type(doc_type), pointer :: doc - character(len=*), intent(in) :: varname, desc, units - type(time_type), intent(in) :: val - type(time_type), optional, intent(in) :: default - logical, optional, intent(in) :: layoutParam - logical, optional, intent(in) :: debuggingParam + type(doc_type), pointer :: doc !< A pointer to a structure that controls where the + !! documentation occurs and its formatting + character(len=*), intent(in) :: varname !< The name of the parameter being documented + character(len=*), intent(in) :: desc !< A description of the parameter being documented + character(len=*), intent(in) :: units !< The units of the parameter being documented + type(time_type), intent(in) :: val !< The value of the parameter + type(time_type), optional, intent(in) :: default !< The default value of this parameter + logical, optional, intent(in) :: layoutParam !< If present and true, this is a layout parameter. + logical, optional, intent(in) :: debuggingParam !< If present and true, this is a debugging parameter. ! This subroutine handles parameter documentation for time-type variables. ! ### This needs to be written properly! integer :: numspc @@ -407,14 +449,17 @@ subroutine doc_param_time(doc, varname, desc, units, val, default, & end subroutine doc_param_time +!> This subroutine writes out the message and description to the documetation files. subroutine writeMessageAndDesc(doc, vmesg, desc, valueWasDefault, indent, & layoutParam, debuggingParam) - type(doc_type), intent(in) :: doc - character(len=*), intent(in) :: vmesg, desc - logical, optional, intent(in) :: valueWasDefault - integer, optional, intent(in) :: indent - logical, optional, intent(in) :: layoutParam - logical, optional, intent(in) :: debuggingParam + type(doc_type), intent(in) :: doc !< A pointer to a structure that controls where the + !! documentation occurs and its formatting + character(len=*), intent(in) :: vmesg !< A message with the parameter name, units, and default value. + character(len=*), intent(in) :: desc !< A description of the parameter being documented + logical, optional, intent(in) :: valueWasDefault !< If true, this parameter has its default value + integer, optional, intent(in) :: indent !< An amount by which to indent this message + logical, optional, intent(in) :: layoutParam !< If present and true, this is a layout parameter. + logical, optional, intent(in) :: debuggingParam !< If present and true, this is a debugging parameter. character(len=mLen) :: mesg integer :: start_ind = 1, end_ind, indnt, tab, len_tab, len_nl logical :: all, short, layout, debug @@ -472,8 +517,9 @@ end subroutine writeMessageAndDesc ! ---------------------------------------------------------------------- +!> This function returns a string with a real formatted like '(G)' function real_string(val) - real, intent(in) :: val + real, intent(in) :: val !< The value being written into a string character(len=32) :: real_string ! This function returns a string with a real formatted like '(G)' integer :: len, ind @@ -523,10 +569,14 @@ function real_string(val) real_string = adjustl(real_string) end function real_string -function real_array_string(vals,sep) - character(len=1320) :: real_array_string - real, intent(in) :: vals(:) - character(len=*), optional :: sep +!> Returns a character string of a comma-separated, compact formatted, reals +!> e.g. "1., 2., 5*3., 5.E2", that give the list of values. +function real_array_string(vals, sep) + character(len=1320) :: real_array_string !< The output string listing vals + real, intent(in) :: vals(:) !< The array of values to record + character(len=*), & + optional, intent(in) :: sep !< The separator between successive values, + !! by default it is ', '. ! Returns a character string of a comma-separated, compact formatted, reals ! e.g. "1., 2., 5*3., 5.E2" ! Local variables @@ -562,9 +612,10 @@ function real_array_string(vals,sep) enddo end function real_array_string +!> This function tests whether a real value is encoded in a string. function testFormattedFloatIsReal(str, val) - character(len=*), intent(in) :: str - real, intent(in) :: val + character(len=*), intent(in) :: str !< The string that match val + real, intent(in) :: val !< The value being tested logical :: testFormattedFloatIsReal ! Local variables real :: scannedVal @@ -577,25 +628,31 @@ function testFormattedFloatIsReal(str, val) endif end function testFormattedFloatIsReal +!> This function returns a string with an integer formatted like '(I)' function int_string(val) - integer, intent(in) :: val + integer, intent(in) :: val !< The value being written into a string character(len=24) :: int_string ! This function returns a string with an integer formatted like '(I)' write(int_string, '(i24)') val int_string = adjustl(int_string) end function int_string +!> This function returns a string with an logical formatted like '(L)' function logical_string(val) - logical, intent(in) :: val + logical, intent(in) :: val !< The value being written into a string character(len=24) :: logical_string ! This function returns a string with an logical formatted like '(L)' write(logical_string, '(l24)') val logical_string = adjustl(logical_string) end function logical_string +!> This function returns a string for formatted parameter assignment function define_string(doc,varName,valString,units) - type(doc_type), pointer :: doc - character(len=*), intent(in) :: varName, valString, units + type(doc_type), pointer :: doc !< A pointer to a structure that controls where the + !! documentation occurs and its formatting + character(len=*), intent(in) :: varName !< The name of the parameter being documented + character(len=*), intent(in) :: valString !< A string containing the value of the parameter + character(len=*), intent(in) :: units !< The units of the parameter being documented character(len=mLen) :: define_string ! This function returns a string for formatted parameter assignment integer :: numSpaces @@ -610,9 +667,12 @@ function define_string(doc,varName,valString,units) if (len_trim(units) > 0) define_string = trim(define_string)//" ["//trim(units)//"]" end function define_string +!> This function returns a string for formatted false logicals function undef_string(doc,varName,units) - type(doc_type), pointer :: doc - character(len=*), intent(in) :: varName, units + type(doc_type), pointer :: doc !< A pointer to a structure that controls where the + !! documentation occurs and its formatting + character(len=*), intent(in) :: varName !< The name of the parameter being documented + character(len=*), intent(in) :: units !< The units of the parameter being documented character(len=mLen) :: undef_string ! This function returns a string for formatted false logicals integer :: numSpaces @@ -630,9 +690,12 @@ end function undef_string ! ---------------------------------------------------------------------- +!> This subroutine handles the module documentation subroutine doc_module(doc, modname, desc) - type(doc_type), pointer :: doc - character(len=*), intent(in) :: modname, desc + type(doc_type), pointer :: doc !< A pointer to a structure that controls where the + !! documentation occurs and its formatting + character(len=*), intent(in) :: modname !< The name of the module being documented + character(len=*), intent(in) :: desc !< A description of the module being documented ! This subroutine handles the module documentation character(len=mLen) :: mesg @@ -646,18 +709,26 @@ subroutine doc_module(doc, modname, desc) endif end subroutine doc_module +!> This subroutine handles the subroutine documentation subroutine doc_subroutine(doc, modname, subname, desc) - type(doc_type), pointer :: doc - character(len=*), intent(in) :: modname, subname, desc + type(doc_type), pointer :: doc !< A pointer to a structure that controls where the + !! documentation occurs and its formatting + character(len=*), intent(in) :: modname !< The name of the module being documented + character(len=*), intent(in) :: subname !< The name of the subroutine being documented + character(len=*), intent(in) :: desc !< A description of the subroutine being documented ! This subroutine handles the subroutine documentation if (.not. (is_root_pe() .and. associated(doc))) return call open_doc_file(doc) end subroutine doc_subroutine +!> This subroutine handles the function documentation subroutine doc_function(doc, modname, fnname, desc) - type(doc_type), pointer :: doc - character(len=*), intent(in) :: modname, fnname, desc + type(doc_type), pointer :: doc !< A pointer to a structure that controls where the + !! documentation occurs and its formatting + character(len=*), intent(in) :: modname !< The name of the module being documented + character(len=*), intent(in) :: fnname !< The name of the function being documented + character(len=*), intent(in) :: desc !< A description of the function being documented ! This subroutine handles the function documentation if (.not. (is_root_pe() .and. associated(doc))) return call open_doc_file(doc) @@ -667,9 +738,18 @@ end subroutine doc_function ! ---------------------------------------------------------------------- subroutine doc_init(docFileBase, doc, minimal, complete, layout, debugging) - character(len=*), intent(in) :: docFileBase - type(doc_type), pointer :: doc - logical, optional, intent(in) :: minimal, complete, layout, debugging + character(len=*), intent(in) :: docFileBase !< The base file name for this set of parameters, + !! for example MOM_parameter_doc + type(doc_type), pointer :: doc !< A pointer to a structure that controls where the + !! documentation occurs and its formatting + logical, optional, intent(in) :: minimal !< If present and true, write out the files (.short) documenting + !! those parameters that do not take on their default values. + logical, optional, intent(in) :: complete !< If present and true, write out the (.all) files documenting all + !! parameters + logical, optional, intent(in) :: layout !< If present and true, write out the (.layout) files documenting + !! the layout parameters + logical, optional, intent(in) :: debugging !< If present and true, write out the (.debugging) files documenting + !! the debugging parameters ! Arguments: docFileBase - The name of the doc file. ! (inout) doc - The doc_type to populate. @@ -685,8 +765,12 @@ subroutine doc_init(docFileBase, doc, minimal, complete, layout, debugging) end subroutine doc_init +!< This subroutine allocates and populates a structure that controls where the +!! documentation occurs and its formatting, and opens up the files controlled +!! by this structure subroutine open_doc_file(doc) - type(doc_type), pointer :: doc + type(doc_type), pointer :: doc !< A pointer to a structure that controls where the + !! documentation occurs and its formatting logical :: opened, new_file integer :: ios @@ -781,6 +865,7 @@ subroutine open_doc_file(doc) end subroutine open_doc_file +! Find an unused unit number, returning >0 if found, and triggering a FATAL error if not. function find_unused_unit_number() ! Find an unused unit number. ! Returns >0 if found. FATAL if not. @@ -794,8 +879,11 @@ function find_unused_unit_number() "doc_init failed to find an unused unit number.") end function find_unused_unit_number +!< This subroutine closes the the files controlled by doc, and sets flags in +!! doc to indicate that parameterization is no longer permitted. subroutine doc_end(doc) - type(doc_type), pointer :: doc + type(doc_type), pointer :: doc !< A pointer to a structure that controls where the + !! documentation occurs and its formatting type(link_msg), pointer :: this, next if (.not.associated(doc)) return @@ -832,9 +920,13 @@ end subroutine doc_end ! ----------------------------------------------------------------------------- +!> Returns true if documentation has already been written function mesgHasBeenDocumented(doc,varName,mesg) - type(doc_type), pointer :: doc - character(len=*), intent(in) :: varName, mesg + type(doc_type), pointer :: doc !< A pointer to a structure that controls where the + !! documentation occurs and its formatting + character(len=*), intent(in) :: varName !< The name of the parameter being documented + character(len=*), intent(in) :: mesg !< A message with parameter values, defaults, and descriptions + !! to compare with the message that was written previously logical :: mesgHasBeenDocumented ! Returns true if documentation has already been written type(link_msg), pointer :: newLink, this, last