mom_document module reference

The subroutines here provide hooks for document generation functions at various levels of granularity.

More…

Data Types

doc_type

A structure that controls where the documentation occurs, its veborsity and formatting.

link_msg

A linked list of the parameter documentation messages that have been issued so far.

Functions/Subroutines

doc_param_none()

This subroutine handles parameter documentation with no value.

doc_param_logical()

This subroutine handles parameter documentation for logicals.

doc_param_logical_array()

This subroutine handles parameter documentation for arrays of logicals.

doc_param_int()

This subroutine handles parameter documentation for integers.

doc_param_int_array()

This subroutine handles parameter documentation for arrays of integers.

doc_param_real()

This subroutine handles parameter documentation for reals.

doc_param_real_array()

This subroutine handles parameter documentation for arrays of reals.

doc_param_char()

This subroutine handles parameter documentation for character strings.

doc_openblock()

This subroutine handles documentation for opening a parameter block.

doc_closeblock()

This subroutine handles documentation for closing a parameter block.

doc_param_time()

This subroutine handles parameter documentation for time-type variables.

writemessageanddesc()

This subroutine writes out the message and description to the documetation files.

time_string()

This function returns a string with a time type formatted as seconds (perhaps including a fractional number of seconds) and days.

real_string()

This function returns a string with a real formatted like ‘(G)’.

real_array_string()

Returns a character string of a comma-separated, compact formatted, reals e.g.

testformattedfloatisreal()

This function tests whether a real value is encoded in a string.

int_string()

This function returns a string with an integer formatted like ‘(I)’.

logical_string()

This function returns a string with an logical formatted like ‘(L)’.

define_string()

This function returns a string for formatted parameter assignment.

undef_string()

This function returns a string for formatted false logicals.

doc_module()

This subroutine handles the module documentation.

doc_subroutine()

This subroutine handles the subroutine documentation.

doc_function()

This subroutine handles the function documentation.

doc_init()

Initialize the parameter documentation.

open_doc_file()

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.

find_unused_unit_number()

Find an unused unit number, returning >0 if found, and triggering a FATAL error if not.

doc_end()

This subroutine closes the the files controlled by doc, and sets flags in doc to indicate that parameterization is no longer permitted.

mesghasbeendocumented()

Returns true if documentation has already been written.

Detailed Description

The subroutines here provide hooks for document generation functions at various levels of granularity.

Type Documentation

type mom_document/doc_type

A structure that controls where the documentation occurs, its veborsity and formatting.

Type fields
  • % unitall [integer] :: The open unit number for docFileBase + .all.

  • % unitshort [integer] :: The open unit number for docFileBase + .short.

  • % unitlayout [integer] :: The open unit number for docFileBase + .layout.

  • % unitdebugging [integer] :: The open unit number for docFileBase + .debugging.

  • % filesareopen [logical] :: True if any files were successfully opened.

  • % docfilebase [character (len= mlen )] :: The basename of the files where run-time parameters, settings and defaults are documented.

  • % complete [logical] :: If true, document all parameters.

  • % minimal [logical] :: If true, document non-default parameters.

  • % layout [logical] :: If true, document layout parameters.

  • % debugging [logical] :: If true, document debugging parameters.

  • % definesyntax [logical] :: If true, use ‘#def’ syntax instead of a=b syntax.

  • % warnonconflicts [logical] :: Cause a WARNING error if defaults differ.

  • % commentcolumn [integer] :: Number of spaces before the comment marker.

  • % max_line_len [integer] :: The maximum length of message lines.

  • % chain_msg [type( link_msg ),pointer] :: Database of messages.

  • % blockprefix [character (len=240)] :: The full name of the current block.

A linked list of the parameter documentation messages that have been issued so far.

Type fields
  • % next [type( link_msg ),pointer, private] :: Facilitates linked list.

  • % name [character (len=80),private] :: Parameter name.

  • % msg [character (len=620),private] :: Parameter value and default.

Function/Subroutine Documentation

subroutine mom_document/doc_param_none(doc, varname, desc, units)

This subroutine handles parameter documentation with no value.

Parameters
  • doc :: A pointer to a structure that controls where the documentation occurs and its formatting

  • varname :: [in] The name of the parameter being documented

  • desc :: [in] A description of the parameter being documented

  • units :: [in] The units of the parameter being documented

Call to

mesghasbeendocumented open_doc_file writemessageanddesc

subroutine mom_document/doc_param_logical(doc, varname, desc, units, val, default, layoutParam, debuggingParam, like_default)

This subroutine handles parameter documentation for logicals.

Parameters
  • doc :: A pointer to a structure that controls where the documentation occurs and its formatting

  • varname :: [in] The name of the parameter being documented

  • desc :: [in] A description of the parameter being documented

  • units :: [in] The units of the parameter being documented

  • val :: [in] The value of this parameter

  • default :: [in] The default value of this parameter

  • layoutparam :: [in] If present and true, this is a layout parameter.

  • debuggingparam :: [in] If present and true, this is a debugging parameter.

  • like_default :: [in] If present and true, log this parameter as though it has the default value, even if there is no default.

Call to

define_string mesghasbeendocumented open_doc_file string_false string_true undef_string writemessageanddesc

subroutine mom_document/doc_param_logical_array(doc, varname, desc, units, vals, default, layoutParam, debuggingParam, like_default)

This subroutine handles parameter documentation for arrays of logicals.

Parameters
  • doc :: A pointer to a structure that controls where the documentation occurs and its formatting

  • varname :: [in] The name of the parameter being documented

  • desc :: [in] A description of the parameter being documented

  • units :: [in] The units of the parameter being documented

  • vals :: [in] The array of values to record

  • default :: [in] The default value of this parameter

  • layoutparam :: [in] If present and true, this is a layout parameter.

  • debuggingparam :: [in] If present and true, this is a debugging parameter.

  • like_default :: [in] If present and true, log this parameter as though it has the default value, even if there is no default.

Call to

define_string mesghasbeendocumented open_doc_file string_false string_true writemessageanddesc

subroutine mom_document/doc_param_int(doc, varname, desc, units, val, default, layoutParam, debuggingParam, like_default)

This subroutine handles parameter documentation for integers.

Parameters
  • doc :: A pointer to a structure that controls where the documentation occurs and its formatting

  • varname :: [in] The name of the parameter being documented

  • desc :: [in] A description of the parameter being documented

  • units :: [in] The units of the parameter being documented

  • val :: [in] The value of this parameter

  • default :: [in] The default value of this parameter

  • layoutparam :: [in] If present and true, this is a layout parameter.

  • debuggingparam :: [in] If present and true, this is a debugging parameter.

  • like_default :: [in] If present and true, log this parameter as though it has the default value, even if there is no default.

Call to

define_string int_string mesghasbeendocumented open_doc_file writemessageanddesc

subroutine mom_document/doc_param_int_array(doc, varname, desc, units, vals, default, layoutParam, debuggingParam, like_default)

This subroutine handles parameter documentation for arrays of integers.

Parameters
  • doc :: A pointer to a structure that controls where the documentation occurs and its formatting

  • varname :: [in] The name of the parameter being documented

  • desc :: [in] A description of the parameter being documented

  • units :: [in] The units of the parameter being documented

  • vals :: [in] The array of values to record

  • default :: [in] The default value of this parameter

  • layoutparam :: [in] If present and true, this is a layout parameter.

  • debuggingparam :: [in] If present and true, this is a debugging parameter.

  • like_default :: [in] If present and true, log this parameter as though it has the default value, even if there is no default.

Call to

define_string int_string mesghasbeendocumented open_doc_file writemessageanddesc

subroutine mom_document/doc_param_real(doc, varname, desc, units, val, default, debuggingParam, like_default)

This subroutine handles parameter documentation for reals.

Parameters
  • doc :: A pointer to a structure that controls where the documentation occurs and its formatting

  • varname :: [in] The name of the parameter being documented

  • desc :: [in] A description of the parameter being documented

  • units :: [in] The units of the parameter being documented

  • val :: [in] The value of this parameter

  • default :: [in] The default value of this parameter

  • debuggingparam :: [in] If present and true, this is a debugging parameter.

  • like_default :: [in] If present and true, log this parameter as though it has the default value, even if there is no default.

Call to

define_string mesghasbeendocumented open_doc_file real_string writemessageanddesc

subroutine mom_document/doc_param_real_array(doc, varname, desc, units, vals, default, debuggingParam, like_default)

This subroutine handles parameter documentation for arrays of reals.

Parameters
  • doc :: A pointer to a structure that controls where the documentation occurs and its formatting

  • varname :: [in] The name of the parameter being documented

  • desc :: [in] A description of the parameter being documented

  • units :: [in] The units of the parameter being documented

  • vals :: [in] The array of values to record

  • default :: [in] The default value of this parameter

  • debuggingparam :: [in] If present and true, this is a debugging parameter.

  • like_default :: [in] If present and true, log this parameter as though it has the default value, even if there is no default.

Call to

define_string mesghasbeendocumented open_doc_file real_array_string real_string writemessageanddesc

subroutine mom_document/doc_param_char(doc, varname, desc, units, val, default, layoutParam, debuggingParam, like_default)

This subroutine handles parameter documentation for character strings.

Parameters
  • doc :: A pointer to a structure that controls where the documentation occurs and its formatting

  • varname :: [in] The name of the parameter being documented

  • desc :: [in] A description of the parameter being documented

  • units :: [in] The units of the parameter being documented

  • val :: [in] The value of the parameter

  • default :: [in] The default value of this parameter

  • layoutparam :: [in] If present and true, this is a layout parameter.

  • debuggingparam :: [in] If present and true, this is a debugging parameter.

  • like_default :: [in] If present and true, log this parameter as though it has the default value, even if there is no default.

Call to

define_string mesghasbeendocumented open_doc_file writemessageanddesc

subroutine mom_document/doc_openblock(doc, blockName, desc)

This subroutine handles documentation for opening a parameter block.

Parameters
  • doc :: A pointer to a structure that controls where the documentation occurs and its formatting

  • blockname :: [in] The name of the parameter block being opened

  • desc :: [in] A description of the parameter block being opened

Call to

open_doc_file writemessageanddesc

Called from

mom_file_parser::openparameterblock

subroutine mom_document/doc_closeblock(doc, blockName)

This subroutine handles documentation for closing a parameter block.

Parameters
  • doc :: A pointer to a structure that controls where the documentation occurs and its formatting

  • blockname :: [in] The name of the parameter block being closed

Call to

open_doc_file writemessageanddesc

Called from

mom_file_parser::closeparameterblock

subroutine mom_document/doc_param_time(doc, varname, desc, val, default, units, debuggingParam, like_default)

This subroutine handles parameter documentation for time-type variables.

Parameters
  • doc :: A pointer to a structure that controls where the documentation occurs and its formatting

  • varname :: [in] The name of the parameter being documented

  • desc :: [in] A description of the parameter being documented

  • val :: [in] The value of the parameter

  • default :: [in] The default value of this parameter

  • units :: [in] The units of the parameter being documented

  • debuggingparam :: [in] If present and true, this is a debugging parameter.

  • like_default :: [in] If present and true, log this parameter as though it has the default value, even if there is no default.

Call to

define_string mesghasbeendocumented open_doc_file time_string writemessageanddesc

subroutine mom_document/writemessageanddesc(doc, vmesg, desc, valueWasDefault, indent, layoutParam, debuggingParam)

This subroutine writes out the message and description to the documetation files.

Parameters
  • doc :: [in] A pointer to a structure that controls where the documentation occurs and its formatting

  • vmesg :: [in] A message with the parameter name, units, and default value.

  • desc :: [in] A description of the parameter being documented

  • valuewasdefault :: [in] If true, this parameter has its default value

  • indent :: [in] An amount by which to indent this message

  • layoutparam :: [in] If present and true, this is a layout parameter.

  • debuggingparam :: [in] If present and true, this is a debugging parameter.

Called from

doc_closeblock doc_module doc_openblock doc_param_char doc_param_int doc_param_int_array doc_param_logical doc_param_logical_array doc_param_none doc_param_real doc_param_real_array doc_param_time

function mom_document/time_string(time) [character(len=40)]

This function returns a string with a time type formatted as seconds (perhaps including a fractional number of seconds) and days.

Parameters

time :: [in] The time type being translated

Call to

int_string

Called from

doc_param_time

function mom_document/real_string(val) [character(len=32)]

This function returns a string with a real formatted like ‘(G)’.

Parameters

val :: [in] The value being written into a string

Call to

testformattedfloatisreal

Called from

doc_param_real doc_param_real_array real_array_string

function mom_document/real_array_string(vals, sep) [character(len=:)]

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.

Return

undefined :: The output string listing vals

Parameters
  • vals :: [in] The array of values to record

  • sep :: [in] The separator between successive values,

Call to

int_string real_string

Called from

doc_param_real_array

function mom_document/testformattedfloatisreal(str, val) [logical]

This function tests whether a real value is encoded in a string.

Parameters
  • str :: [in] The string that match val

  • val :: [in] The value being tested

Called from

real_string

function mom_document/int_string(val) [character(len=24)]

This function returns a string with an integer formatted like ‘(I)’.

Parameters

val :: [in] The value being written into a string

Called from

doc_param_int doc_param_int_array real_array_string time_string

function mom_document/logical_string(val) [character(len=24)]

This function returns a string with an logical formatted like ‘(L)’.

Parameters

val :: [in] The value being written into a string

function mom_document/define_string(doc, varName, valString, units) [character(len=mlen)]

This function returns a string for formatted parameter assignment.

Parameters
  • doc :: A pointer to a structure that controls where the documentation occurs and its formatting

  • varname :: [in] The name of the parameter being documented

  • valstring :: [in] A string containing the value of the parameter

  • units :: [in] The units of the parameter being documented

Call to

mlen

Called from

doc_param_char doc_param_int doc_param_int_array doc_param_logical doc_param_logical_array doc_param_real doc_param_real_array doc_param_time

function mom_document/undef_string(doc, varName, units) [character(len=mlen)]

This function returns a string for formatted false logicals.

Parameters
  • doc :: A pointer to a structure that controls where the documentation occurs and its formatting

  • varname :: [in] The name of the parameter being documented

  • units :: [in] The units of the parameter being documented

Call to

string_false

Called from

doc_param_logical

subroutine mom_document/doc_module(doc, modname, desc, log_to_all, all_default, layoutMod, debuggingMod)

This subroutine handles the module documentation.

Parameters
  • doc :: A pointer to a structure that controls where the documentation occurs and its formatting

  • modname :: [in] The name of the module being documented

  • desc :: [in] A description of the module being documented

  • log_to_all :: [in] If present and true, log this parameter to the …_doc.all files, even if this module also has layout or debugging parameters.

  • all_default :: [in] If true, all parameters take their default values.

  • layoutmod :: [in] If present and true, this module has layout parameters.

  • debuggingmod :: [in] If present and true, this module has debugging parameters.

Call to

open_doc_file writemessageanddesc

subroutine mom_document/doc_subroutine(doc, modname, subname, desc)

This subroutine handles the subroutine documentation.

Parameters
  • doc :: A pointer to a structure that controls where the documentation occurs and its formatting

  • modname :: [in] The name of the module being documented

  • subname :: [in] The name of the subroutine being documented

  • desc :: [in] A description of the subroutine being documented

Call to

open_doc_file

subroutine mom_document/doc_function(doc, modname, fnname, desc)

This subroutine handles the function documentation.

Parameters
  • doc :: A pointer to a structure that controls where the documentation occurs and its formatting

  • modname :: [in] The name of the module being documented

  • fnname :: [in] The name of the function being documented

  • desc :: [in] A description of the function being documented

Call to

open_doc_file

subroutine mom_document/doc_init(docFileBase, doc, minimal, complete, layout, debugging)

Initialize the parameter documentation.

Parameters
  • docfilebase :: [in] The base file name for this set of parameters, for example MOM_parameter_doc

  • doc :: A pointer to a structure that controls where the documentation occurs and its formatting

  • minimal :: [in] If present and true, write out the files (.short) documenting those parameters that do not take on their default values.

  • complete :: [in] If present and true, write out the (.all) files documenting all parameters

  • layout :: [in] If present and true, write out the (.layout) files documenting the layout parameters

  • debugging :: [in] If present and true, write out the (.debugging) files documenting the debugging parameters

subroutine mom_document/open_doc_file(doc)

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.

Parameters

doc :: A pointer to a structure that controls where the documentation occurs and its formatting

Call to

find_unused_unit_number mom_error_handler::mom_error

Called from

doc_closeblock doc_function doc_module doc_openblock doc_param_char doc_param_int doc_param_int_array doc_param_logical doc_param_logical_array doc_param_none doc_param_real doc_param_real_array doc_param_time doc_subroutine

function mom_document/find_unused_unit_number() [integer]

Find an unused unit number, returning >0 if found, and triggering a FATAL error if not.

Call to

mom_error_handler::mom_error

Called from

open_doc_file

subroutine mom_document/doc_end(doc)

This subroutine closes the the files controlled by doc, and sets flags in doc to indicate that parameterization is no longer permitted.

Parameters

doc :: A pointer to a structure that controls where the documentation occurs and its formatting

function mom_document/mesghasbeendocumented(doc, varName, mesg) [logical]

Returns true if documentation has already been written.

Parameters
  • doc :: A pointer to a structure that controls where the documentation occurs and its formatting

  • varname :: [in] The name of the parameter being documented

  • mesg :: [in] A message with parameter values, defaults, and descriptions to compare with the message that was written previously

Call to

mom_error_handler::mom_error

Called from

doc_param_char doc_param_int doc_param_int_array doc_param_logical doc_param_logical_array doc_param_none doc_param_real doc_param_real_array doc_param_time