Add docstrings and rearrange code for clarity

Author: lrennels

src/components/adder.jl

@@ -13,4 +13,3 @@ using Mimi
         v.output[t] = @allow_missing(p.input[t]) + p.add[t]
     end
 end
-

src/core/build.jl

@@ -1,5 +1,11 @@
-connector_comp_name(i::Int) = Symbol("ConnectorComp$i")
+"""
+    _substitute_views!(vals::Array{T, N}, comp_def) where {T, N}
 
+For each value in `vals`, if the value is a `TimestepArray` swap in a new 
+TimestepArray with the same type parameterization but with its `data` field 
+holding a view of the original value's `data` defined by the first and last
+indices of Component `comp_def`.
+"""
 # helper function to substitute views for data 
 function _substitute_views!(vals::Array{T, N}, comp_def) where {T, N}
     times = [keys(comp_def.dim_dict[:time])...]
@@ -12,6 +18,13 @@ function _substitute_views!(vals::Array{T, N}, comp_def) where {T, N}
     end
 end
 
+"""
+    _get_view(val::TimestepArray{T_TS, T, N, ti, S}, first_idx, last_idx) where {T_TS, T, N, ti, S}
+
+Return a TimestepArray with the same type parameterization as the `val` TimestepArray,
+but with its `data` field holding a view of the `val.data` based on the entered
+`first-idx` and `last_idx`. 
+"""
 function _get_view(val::TimestepArray{T_TS, T, N, ti, S}, first_idx, last_idx) where {T_TS, T, N, ti, S}
 
     idxs  = Array{Any}(fill(:, N))
@@ -21,7 +34,12 @@ function _get_view(val::TimestepArray{T_TS, T, N, ti, S}, first_idx, last_idx) w
     return TimestepArray{T_TS, T, N, ti}(val.data isa SubArray ? view(val.data.parent, idxs...) : view(val.data, idxs...))
 end
 
-# Return the datatype to use for instance variables/parameters
+"""
+    _instance_datatype(md::ModelDef, def::AbstractDatumDef)
+
+Return the datatype of the AbstractDataumDef `def` in ModelDef `md`, which will
+be used to create ModelInstance instance variables and parameters.    
+"""
 function _instance_datatype(md::ModelDef, def::AbstractDatumDef)
     dtype = def.datatype == Number ? number_type(md) : def.datatype
     dims = dim_names(def)
@@ -51,6 +69,13 @@ function _instance_datatype(md::ModelDef, def::AbstractDatumDef)
     return T
 end
 
+"""
+    _instantiate_datum(md::ModelDef, def::AbstractDatumDef)
+
+Return the parameterized datum, broadly either Scalar or Array, pertaining to 
+AbstractDatumDef `def` in the Model Def `md`, that will support instantiate of parameters 
+and variables.
+"""
 # Create the Ref or Array that will hold the value(s) for a Parameter or Variable
 function _instantiate_datum(md::ModelDef, def::AbstractDatumDef)
     dtype = _instance_datatype(md, def)
@@ -106,7 +131,12 @@ function _instantiate_component_vars(md::ModelDef, comp_def::ComponentDef)
     return ComponentInstanceVariables(names, types, values, paths)
 end
 
-# Creates the top-level vars for the model
+"""
+    function _instantiate_vars(md::ModelDef)
+
+Create the top-level variables for the Model Def `md` and return the dictionary 
+of the resulting ComponentInstanceVariables.
+"""
 function _instantiate_vars(md::ModelDef)
     vdict = Dict{ComponentPath, Any}()
     recurse(md, cd -> vdict[cd.comp_path] = _instantiate_component_vars(md, cd); leaf_only=true)
@@ -207,7 +237,16 @@ function _get_leaf_level_epcs(md::ModelDef, epc::ExternalParameterConnection)
     return leaf_epcs
 end
 
-# Collect all parameters with connections to allocated variable storage
+# generic helper function to get connector component name
+connector_comp_name(i::Int) = Symbol("ConnectorComp$i")
+
+"""
+    _collect_params(md::ModelDef, var_dict::Dict{ComponentPath, Any})
+
+Collect all parameters in ModelDef `md` with connections to allocated variable 
+storage in `var_dict` and return a dictionary of (comp_path, par_name) => ModelParameter 
+elements.
+"""
 function _collect_params(md::ModelDef, var_dict::Dict{ComponentPath, Any})
 
     # @info "Collecting params for $(comp_def.comp_id)"
@@ -251,6 +290,12 @@ function _collect_params(md::ModelDef, var_dict::Dict{ComponentPath, Any})
     return pdict
 end
 
+"""
+    _instantiate_params(comp_def::ComponentDef, par_dict::Dict{Tuple{ComponentPath, Symbol}, Any})
+
+Create the top-level parameters for the Model Def `md` using the parameter dictionary
+`par_dict` and return the resulting ComponentInstanceParameters.
+"""
 function _instantiate_params(comp_def::ComponentDef, par_dict::Dict{Tuple{ComponentPath, Symbol}, Any})
     # @info "Instantiating params for $(comp_def.comp_path)"
     comp_path = comp_def.comp_path
@@ -263,7 +308,16 @@ function _instantiate_params(comp_def::ComponentDef, par_dict::Dict{Tuple{Compon
     return ComponentInstanceParameters(names, types, vals, paths)
 end
 
-# Return a built leaf or composite LeafComponentInstance
+"""
+    _build(comp_def::ComponentDef,
+                    var_dict::Dict{ComponentPath, Any},
+                    par_dict::Dict{Tuple{ComponentPath, Symbol}, Any},
+                    time_bounds::Tuple{Int, Int})
+
+Return a built leaf or composite LeafComponentInstance created using ComponentDef
+`comp_def`, variables and parameters from `var_dict` and `par_dict` and the time 
+bounds set by `time_bounds`.
+"""
 function _build(comp_def::ComponentDef,
                 var_dict::Dict{ComponentPath, Any},
                 par_dict::Dict{Tuple{ComponentPath, Symbol}, Any},
@@ -278,6 +332,16 @@ function _build(comp_def::ComponentDef,
     return LeafComponentInstance(comp_def, vars, pars, time_bounds)
 end
 
+"""
+    _build(comp_def::AbstractCompositeComponentDef,
+                    var_dict::Dict{ComponentPath, Any},
+                    par_dict::Dict{Tuple{ComponentPath, Symbol}, Any},
+                    time_bounds::Tuple{Int, Int})
+
+Return a built CompositeComponentInstance created using AbstractCompositeComponentDef
+`comp_def`, variables and parameters from `var_dict` and `par_dict` and the time 
+bounds set by `time_bounds`.
+"""
 function _build(comp_def::AbstractCompositeComponentDef,
                 var_dict::Dict{ComponentPath, Any},
                 par_dict::Dict{Tuple{ComponentPath, Symbol}, Any},
@@ -318,6 +382,11 @@ function _get_parameters(comp_def::AbstractCompositeComponentDef)
     return parameters
 end
 
+"""
+    _build(md::ModelDef)
+
+Build ModelDef `md` (lowest build function called by `build(md::ModelDef)`) and return the ModelInstance..
+"""
 function _build(md::ModelDef)
 
     # @info "_build(md)"
@@ -347,13 +416,23 @@ function _build(md::ModelDef)
     return mi
 end
 
+"""
+    build(m::Model)
+
+Build Model `m` and return the ModelInstance.
+"""
 function build(m::Model)    
     # Reference a copy in the ModelInstance to avoid changes underfoot
     md = deepcopy(m.md)
     mi = _build(md)
     return mi
 end
 
+"""
+    build!(m::Model)
+
+Build Model `m` for and dirty `m`'s ModelDef.
+"""
 function build!(m::Model)
     m.mi = build(m)
     m.md.dirty = false
@@ -384,6 +463,11 @@ function Base.run(mm::MarginalModel; ntimesteps::Int=typemax(Int))
     run(mm.modified, ntimesteps=ntimesteps)
 end
 
+"""
+    build!(mm::MarginalModel)
+
+Build MarginalModel `mm` by building both its `base` and `modified models`.
+"""
 function build!(mm::MarginalModel)
     build!(mm.base)
     build!(mm.modified)

src/core/connections.jl

@@ -49,6 +49,15 @@ end
 # Default string, string unit check function
 verify_units(unit1::AbstractString, unit2::AbstractString) = (unit1 == unit2)
 
+"""
+    _check_labels(obj::AbstractCompositeComponentDef,
+                comp_def::AbstractComponentDef, param_name::Symbol, 
+                mod_param::ArrayModelParameter)
+
+Check that the labels of the ArrayModelParameter `mod_param` match the labels
+of the model parameter `param_name` in component `comp_def` of object `obj`, 
+including datatype and dimensions. 
+"""
 function _check_labels(obj::AbstractCompositeComponentDef,
                        comp_def::AbstractComponentDef, param_name::Symbol, mod_param::ArrayModelParameter)
     param_def = parameter(comp_def, param_name)
@@ -100,6 +109,13 @@ function connect_param!(obj::AbstractCompositeComponentDef, comp_name::Symbol,
     connect_param!(obj, comp_def, param_name, model_param_name, check_labels=check_labels)
 end
 
+"""
+    connect_param!(obj::AbstractCompositeComponentDef, comp_def::AbstractComponentDef,
+                    param_name::Symbol, model_param_name::Symbol; check_labels::Bool=true)
+
+Connect a parameter `param_name` in the component `comp_def` of composite `obj` to
+the model parameter `model_param_name`.
+"""
 function connect_param!(obj::AbstractCompositeComponentDef, comp_def::AbstractComponentDef,
                         param_name::Symbol, model_param_name::Symbol; check_labels::Bool=true)
     mod_param = model_param(obj, model_param_name)
@@ -232,6 +248,23 @@ Try calling:
     return nothing
 end
 
+"""
+    connect_param!(obj::AbstractCompositeComponentDef,
+                    dst_comp_name::Symbol, dst_par_name::Symbol,
+                    src_comp_name::Symbol, src_var_name::Symbol,
+                    backup::Union{Nothing, Array}=nothing; ignoreunits::Bool=false, 
+                    backup_offset::Union{Nothing, Int} = nothing)
+
+Bind the parameter `dst_par_name` of one component `dst_comp_name` of composite `obj` to a
+variable `src_var_name` in another component `src_comp_name` of the same model using
+`backup` to provide default values and the `ignoreunits` flag to indicate the need to
+check match units between the two.  The `backup_offset` argument, which is only valid 
+when `backup` data has been set, indicates that the backup data should be used for
+a specified number of timesteps after the source component begins. ie. the value would be 
+`1` if the destination component parameter should only use the source component 
+data for the second timestep and beyond.
+"""
+
 function connect_param!(obj::AbstractCompositeComponentDef,
                         dst_comp_name::Symbol, dst_par_name::Symbol,
                         src_comp_name::Symbol, src_var_name::Symbol,
@@ -368,9 +401,9 @@ function unconnected_params(obj::AbstractCompositeComponentDef)
 end
 
 """
-    set_leftover_params!(m::Model, parameters::Dict)
+    set_leftover_params!(md::ModelDef, parameters::Dict{T, Any}) 
 
-Set all of the parameters in model `m` that don't have a value and are not connected
+Set all of the parameters in `ModelDef` `md` that don't have a value and are not connected
 to some other component to a value from a dictionary `parameters`. This method assumes
 the dictionary keys are strings that match the names of unset parameters in the model,
 and all resulting new model parameters will be shared parameters.
@@ -644,8 +677,12 @@ function update_param!(md::ModelDef, comp_name::Symbol, param_name::Symbol, valu
 
 end
 
-function _update_param!(obj::AbstractCompositeComponentDef,
-                        name::Symbol, value)
+"""
+    _update_param!(obj::AbstractCompositeComponentDef, name::Symbol, value)
+
+Update the `value` of the model parameter `name` in Model Def `md`.
+"""
+function _update_param!(obj::AbstractCompositeComponentDef, name::Symbol, value)
     param = model_param(obj, name, missing_ok=true)
     if param === nothing
         error("Cannot update parameter; $name not found in composite's model parameters.")
@@ -660,6 +697,11 @@ function _update_param!(obj::AbstractCompositeComponentDef,
     dirty!(obj)
 end
 
+"""
+    _update_scalar_param!(param::ScalarModelParameter, name, value)
+
+Update the `value` of the scalar model parameter `param`.
+"""
 function _update_scalar_param!(param::ScalarModelParameter, name, value)
     if ! (value isa typeof(param.value))
         try
@@ -672,6 +714,11 @@ function _update_scalar_param!(param::ScalarModelParameter, name, value)
     nothing
 end
 
+"""
+    _update_array_param!(obj::AbstractCompositeComponentDef, name, value)
+
+Update the `value` of the array model parameter `name` in object `obj`.
+"""
 function _update_array_param!(obj::AbstractCompositeComponentDef, name, value)
 
     # Get original parameter
@@ -735,6 +782,11 @@ function update_params!(obj::AbstractCompositeComponentDef, parameters::Dict; up
     nothing
 end
 
+"""
+    add_connector_comps!(obj::AbstractCompositeComponentDef)
+
+Add all the needed Mimi connector components to object `obj`.
+"""
 function add_connector_comps!(obj::AbstractCompositeComponentDef)
     conns = internal_param_conns(obj)
     i = 1 # counter to track the number of connector comps added

src/core/defcomp.jl

@@ -200,7 +200,7 @@ macro defcomp(comp_name, ex)
             continue
         end
 
-        # DEPRECATION - EVENTUALLY REMOVE
+        # DEPRECATION
         if @capture(elt, name_::datum_type_ = elt_type_(args__))
             error("The following syntax has been deprecated in @defcomp: \"$name::$datum_type = $elt_type(...)\". Use curly bracket syntax instead: \"$name = $elt_type{$datum_type}(...)\"")
         elseif ! @capture(elt, name_ = (elt_type_{datum_type_}(args__) | elt_type_(args__)))