mom_document module reference¶

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

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.

type mom_document/link_msg¶

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

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.

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.

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.

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.

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.

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.

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.

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

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

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.

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 mom_document::doc_param::doc_param_char mom_document::doc_param::doc_param_int mom_document::doc_param::doc_param_int_array mom_document::doc_param::doc_param_logical mom_document::doc_param::doc_param_logical_array mom_document::doc_param::doc_param_none mom_document::doc_param::doc_param_real mom_document::doc_param::doc_param_real_array mom_document::doc_param::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:: mom_document::doc_param::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:: mom_document::doc_param::doc_param_real mom_document::doc_param::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:

mom_document::doc_param::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:: mom_document::doc_param::doc_param_int mom_document::doc_param::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:

mom_document::doc_param::doc_param_char mom_document::doc_param::doc_param_int mom_document::doc_param::doc_param_int_array mom_document::doc_param::doc_param_logical mom_document::doc_param::doc_param_logical_array mom_document::doc_param::doc_param_real mom_document::doc_param::doc_param_real_array mom_document::doc_param::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:

mom_document::doc_param::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 mom_document::doc_param::doc_param_char mom_document::doc_param::doc_param_int mom_document::doc_param::doc_param_int_array mom_document::doc_param::doc_param_logical mom_document::doc_param::doc_param_logical_array mom_document::doc_param::doc_param_none mom_document::doc_param::doc_param_real mom_document::doc_param::doc_param_real_array mom_document::doc_param::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:

mom_document::doc_param::doc_param_char mom_document::doc_param::doc_param_int mom_document::doc_param::doc_param_int_array mom_document::doc_param::doc_param_logical mom_document::doc_param::doc_param_logical_array mom_document::doc_param::doc_param_none mom_document::doc_param::doc_param_real mom_document::doc_param::doc_param_real_array mom_document::doc_param::doc_param_time