Merge pull request #557 from LCSB-BioCore/mk-codeloc-macros

improve macro-related documentation

src/base/macros/change_bounds.jl

+"""
+    @_change_bounds_fn ModelType IdxType [plural] [inplace] begin ... end
+
+A helper for creating simple bounds-changing function similar to
+[`change_bounds`](@ref).
+"""
 macro _change_bounds_fn(model_type, idx_type, args...)
     body = last(args)
     typeof(body) == Expr || throw(DomainError(body, "missing function body"))
@@ -41,10 +47,18 @@ macro _change_bounds_fn(model_type, idx_type, args...)
     ```
     """
 
-    return :(@doc $docstring $fname(
-        model::$model_type,
-        $idx_var::$idx_type;
-        lower = $missing_default,
-        upper = $missing_default,
-    ) = $body)
+    Expr(
+        :macrocall,
+        Symbol("@doc"),
+        __source__,
+        docstring,
+        :(
+            $fname(
+                model::$model_type,
+                $idx_var::$idx_type;
+                lower = $missing_default,
+                upper = $missing_default,
+            ) = $body
+        ),
+    )
 end

src/base/macros/remove_item.jl

+
+"""
+    @ _remove_fn objname ModelType IndexType [plural] [inplace] begin ... end
+
+A helper for creating functions that follow the `remove_objname` template, such
+as [`remove_metabolites`](@ref) and [`remove_reaction`](@ref).
+"""
 macro _remove_fn(objname, model_type, idx_type, args...)
     body = last(args)
     typeof(body) == Expr || throw(DomainError(body, "missing function body"))
@@ -24,5 +31,11 @@ macro _remove_fn(objname, model_type, idx_type, args...)
     $(inplace ? "in-place" : "and return the modified model").
     """
 
-    return :(@doc $docstring $fname(model::$model_type, $idx_var::$idx_type) = $body)
+    Expr(
+        :macrocall,
+        Symbol("@doc"),
+        __source__,
+        docstring,
+        :($fname(model::$model_type, $idx_var::$idx_type) = $body),
+    )
 end

src/base/macros/serialized.jl

 """
-    _serialized_change_unwrap(fn::Symbol)
+    @_serialized_change_unwrap function
 
-Creates a simple wrapper structure that calls a function transparently on the
-internal precached model. Internal type is returned (because this would break
-the consistency of serialization).
+Creates a simple wrapper structure that calls the `function` transparently on
+the internal precached model. Internal type is returned (because this would
+break the consistency of serialization).
 """
 macro _serialized_change_unwrap(fn::Symbol)
     docstring = """
@@ -12,6 +12,14 @@ macro _serialized_change_unwrap(fn::Symbol)
     Calls [`$fn`](@ref) of the internal serialized model type.
     Returns the modified un-serialized model.
     """
-    :(@doc $docstring $fn(model::Serialized, args...; kwargs...) =
-        $fn(unwrap_serialized(model), args...; kwargs...))
+    Expr(
+        :macrocall,
+        Symbol("@doc"),
+        __source__,
+        docstring,
+        :(
+            $fn(model::Serialized, args...; kwargs...) =
+                $fn(unwrap_serialized(model), args...; kwargs...)
+        ),
+    )
 end