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 documentation 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.
`int_array_string()`	Returns a character string of a comma-separated, compact formatted, integers 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 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.

[source]

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.

[source]

Function/Subroutine Documentation

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

This subroutine handles parameter documentation with no value.

Parameters:

doc :: doc A pointer to a structure that controls where the documentation occurs and its formatting
varname :: varname [in] The name of the parameter being documented
desc :: desc [in] A description of the parameter being documented
units :: units [in] The units of the parameter being documented

[source]

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 :: doc A pointer to a structure that controls where the documentation occurs and its formatting
varname :: varname [in] The name of the parameter being documented
desc :: desc [in] A description of the parameter being documented
units :: units [in] The units of the parameter being documented
val :: val [in] The value of this parameter
default :: 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 :: like_default [in] If present and true, log this parameter as though it has the default value, even if there is no default.

[source]

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 :: doc A pointer to a structure that controls where the documentation occurs and its formatting
varname :: varname [in] The name of the parameter being documented
desc :: desc [in] A description of the parameter being documented
units :: units [in] The units of the parameter being documented
vals :: vals [in] The array of values to record
default :: 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 :: like_default [in] If present and true, log this parameter as though it has the default value, even if there is no default.

[source]

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 :: doc A pointer to a structure that controls where the documentation occurs and its formatting
varname :: varname [in] The name of the parameter being documented
desc :: desc [in] A description of the parameter being documented
units :: units [in] The units of the parameter being documented
val :: val [in] The value of this parameter
default :: 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 :: like_default [in] If present and true, log this parameter as though it has the default value, even if there is no default.

[source]

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

This subroutine handles parameter documentation for arrays of integers.

Parameters:

doc :: doc A pointer to a structure that controls where the documentation occurs and its formatting
varname :: varname [in] The name of the parameter being documented
desc :: desc [in] A description of the parameter being documented
units :: units [in] The units of the parameter being documented
vals :: vals [in] The array of values to record
default :: default [in] The uniform default value of this parameter
defaults :: defaults [in] The element-wise default values 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 :: like_default [in] If present and true, log this parameter as though it has the default value, even if there is no default.

[source]

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

This subroutine handles parameter documentation for reals.

Parameters:

doc :: doc A pointer to a structure that controls where the documentation occurs and its formatting
varname :: varname [in] The name of the parameter being documented
desc :: desc [in] A description of the parameter being documented
units :: units [in] The units of the parameter being documented
val :: val [in] The value of this parameter
default :: default [in] The default value of this parameter
debuggingparam :: [in] If present and true, this is a debugging parameter.
like_default :: like_default [in] If present and true, log this parameter as though it has the default value, even if there is no default.

[source]

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

This subroutine handles parameter documentation for arrays of reals.

Parameters:

doc :: doc A pointer to a structure that controls where the documentation occurs and its formatting
varname :: varname [in] The name of the parameter being documented
desc :: desc [in] A description of the parameter being documented
units :: units [in] The units of the parameter being documented
vals :: vals [in] The array of values to record
default :: default [in] A uniform default value of this parameter
defaults :: defaults [in] The element-wise default values of this parameter
debuggingparam :: [in] If present and true, this is a debugging parameter.
like_default :: like_default [in] If present and true, log this parameter as though it has the default value, even if there is no default.

[source]

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 :: doc A pointer to a structure that controls where the documentation occurs and its formatting
varname :: varname [in] The name of the parameter being documented
desc :: desc [in] A description of the parameter being documented
units :: units [in] The units of the parameter being documented
val :: val [in] The value of the parameter
default :: 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 :: like_default [in] If present and true, log this parameter as though it has the default value, even if there is no default.

[source]

subroutine mom_document/doc_openblock(doc, blockName, desc)

This subroutine handles documentation for opening a parameter block.

Parameters:

doc :: 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 :: desc [in] A description of the parameter block being opened

Call to:

open_doc_file writemessageanddesc

[source]

subroutine mom_document/doc_closeblock(doc, blockName)

This subroutine handles documentation for closing a parameter block.

Parameters:

doc :: 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

[source]

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 :: doc A pointer to a structure that controls where the documentation occurs and its formatting
varname :: varname [in] The name of the parameter being documented
desc :: desc [in] A description of the parameter being documented
val :: val [in] The value of the parameter
default :: default [in] The default value of this parameter
units :: units [in] The units of the parameter being documented
debuggingparam :: [in] If present and true, this is a debugging parameter.
like_default :: like_default [in] If present and true, log this parameter as though it has the default value, even if there is no default.

[source]

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

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

Parameters:

doc :: doc [in] A pointer to a structure that controls where the documentation occurs and its formatting
vmesg :: vmesg [in] A message with the parameter name, units, and default value.
desc :: desc [in] A description of the parameter being documented
valuewasdefault :: [in] If true, this parameter has its default value
indent :: 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

[source]

function mom_document/time_string(time)

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

Parameters:: time :: time [in] The time type being translated
Call to:: int_string
Called from:: mom_document::doc_param::doc_param_time

[source]

function mom_document/real_string(val)

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

Parameters:: val :: 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

[source]

function mom_document/real_array_string(vals, 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.

Return:

undefined :: The output string listing vals

Parameters:

vals :: vals [in] The array of values to record
sep :: sep [in] The separator between successive values,

Call to:

int_string real_string

Called from:

mom_document::doc_param::doc_param_real_array

[source]

function mom_document/int_array_string(vals, sep)

Returns a character string of a comma-separated, compact formatted, integers e.g. “1, 2, 7*3, 500”, that give the list of values.

Return:

undefined :: The output string listing vals

Parameters:

vals :: vals [in] The array of values to record
sep :: sep [in] The separator between successive values,

Call to:

int_string

Called from:

mom_document::doc_param::doc_param_int_array

[source]

function mom_document/testformattedfloatisreal(str, val)

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

Parameters:

str :: str [in] The string that match val
val :: val [in] The value being tested

Called from:

real_string

[source]

function mom_document/int_string(val)

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

Parameters:: val :: 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 int_array_string real_array_string time_string

[source]

function mom_document/logical_string(val)

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

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

[source]

function mom_document/define_string(doc, varName, valString, units)

This function returns a string for formatted parameter assignment.

Parameters:

doc :: 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 :: 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

[source]

function mom_document/undef_string(doc, varName, units)

This function returns a string for formatted false logicals.

Parameters:

doc :: 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 :: units [in] The units of the parameter being documented

Call to:

string_false

Called from:

mom_document::doc_param::doc_param_logical

[source]

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

This subroutine handles the module documentation.

Parameters:

doc :: doc A pointer to a structure that controls where the documentation occurs and its formatting
modname :: modname [in] The name of the module being documented
desc :: desc [in] A description of the module being documented
log_to_all :: 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 :: 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

[source]

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

This subroutine handles the subroutine documentation.

Parameters:

doc :: doc A pointer to a structure that controls where the documentation occurs and its formatting
modname :: modname [in] The name of the module being documented
subname :: subname [in] The name of the subroutine being documented
desc :: desc [in] A description of the subroutine being documented

Call to:

open_doc_file

[source]

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

This subroutine handles the function documentation.

Parameters:

doc :: doc A pointer to a structure that controls where the documentation occurs and its formatting
modname :: modname [in] The name of the module being documented
fnname :: fnname [in] The name of the function being documented
desc :: desc [in] A description of the function being documented

Call to:

open_doc_file

[source]

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 :: doc A pointer to a structure that controls where the documentation occurs and its formatting
minimal :: minimal [in] If present and true, write out the files (.short) documenting those parameters that do not take on their default values.
complete :: complete [in] If present and true, write out the (.all) files documenting all parameters
layout :: layout [in] If present and true, write out the (.layout) files documenting the layout parameters
debugging :: debugging [in] If present and true, write out the (.debugging) files documenting the debugging parameters

[source]

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 :: 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

[source]

function mom_document/find_unused_unit_number()

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

[source]

subroutine mom_document/doc_end(doc)

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

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

[source]

function mom_document/mesghasbeendocumented(doc, varName, mesg)

Returns true if documentation has already been written.

Parameters:

doc :: 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 :: 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

[source]