From 26b01daf8dd79ae31d2cd044c3b952ca48086890 Mon Sep 17 00:00:00 2001
From: Mirek Kratochvil <miroslav.kratochvil@uni.lu>
Date: Mon, 10 Jan 2022 15:06:23 +0100
Subject: [PATCH] improve macro-related documentation

- macro-generated functions get properly recognized by documenter and placed to
  the right section
- the generating macros have at least a bit of docs

Closes #508
---
 src/base/macros/change_bounds.jl | 26 ++++++++++++++++++++------
 src/base/macros/remove_item.jl   | 15 ++++++++++++++-
 src/base/macros/serialized.jl    | 20 ++++++++++++++------
 3 files changed, 48 insertions(+), 13 deletions(-)

diff --git a/src/base/macros/change_bounds.jl b/src/base/macros/change_bounds.jl
index c37976082..83a479479 100644
--- a/src/base/macros/change_bounds.jl
+++ b/src/base/macros/change_bounds.jl
@@ -1,3 +1,9 @@
+"""
+    @_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
diff --git a/src/base/macros/remove_item.jl b/src/base/macros/remove_item.jl
index 3a83ae6b6..0caf50c55 100644
--- a/src/base/macros/remove_item.jl
+++ b/src/base/macros/remove_item.jl
@@ -1,3 +1,10 @@
+
+"""
+    @ _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
diff --git a/src/base/macros/serialized.jl b/src/base/macros/serialized.jl
index 031370d8b..65ca54159 100644
--- a/src/base/macros/serialized.jl
+++ b/src/base/macros/serialized.jl
@@ -1,9 +1,9 @@
 """
-    _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