how to document optional terms in budget equations

[klindsay28]

The following text occurs at the end of MOM.F90:

MOM6/src/core/MOM.F90

Lines 3986 to 3997 in 8d80d64

	!! Here is an example 3d heat budget diagnostic for MOM.
	!!
	!! * OPOTTEMPTEND = T_ADVECTION_XY + TH_TENDENCY_VERT_REMAP + OPOTTEMPDIFF + OPOTTEMPPMDIFF
	!! + BOUNDARY_FORCING_HEAT_TENDENCY + FRAZIL_HEAT_TENDENCY
	!!
	!! * OPOTTEMPTEND = net tendency of heat as diagnosed in MOM.F90
	!! * T_ADVECTION_XY = heating of a cell from lateral advection
	!! * TH_TENDENCY_VERT_REMAP = heating of a cell from vertical remapping
	!! * OPOTTEMPDIFF = heating of a cell from diabatic diffusion
	!! * OPOTTEMPPMDIFF = heating of a cell from neutral diffusion
	!! * BOUNDARY_FORCING_HEAT_TENDENCY = heating of cell from boundary fluxes
	!! * FRAZIL_HEAT_TENDENCY = heating of cell from frazil

If one runs MOM6 with KPP via CVMix, then the term KPP_NLtransport_heat also needs to be included.

If one runs MOM6 with USE_LATERAL_BOUNDARY_DIFFUSION, then the term T_lbdxy_cont_tendency also needs to be included.

Despite the text in MOM.F90 being worded as "an example 3d heat budget", I get tripped up that the decomposition of OPOTTEMPTEND is incomplete for some model configurations. Below are some potential approaches to help avoid that confusion, listed in what I suspect is increasing order of implementation complexity:

1. Add a more explicit disclaimer to the text in MOM.F90 that the decomposition does not hold for all model configurations.
2. In the scenarios above, include the terms above in existing terms in the decomposition, ensuring that the decomposition holds for additional model configurations. For example, include KPP_NLtransport_heat in BOUNDARY_FORCING_HEAT_TENDENCY and include T_lbdxy_cont_tendency in OPOTTEMPPMDIFF (and change 'neutral diffusion' in the description to 'lateral mixing').
3. Have the model generate at run time a statement documenting a valid budget decomposition for the configuration being run, and replace the text in MOM.F90 with a blurb pointing to the run time statement.

Thoughts?

(We have the same problem in CESM/POP that some terms in tracer budget decompositions need to be included or not depending on the model configuration. We sidestep the issue by not documenting the decomposition.)

[StephenGriffies]

Thanks @klindsay28 for this comment. I vote for option 2: document more scenarios. Option 3 will take much more thought and code, whereas option 2 merely requires more comments in the code.