From 4fcd733db68d9f02043252c53a20a12ea28f70d0 Mon Sep 17 00:00:00 2001
From: mauro-milella <milella_mauro@live.it>
Date: Fri, 25 Oct 2024 17:57:08 +0200
Subject: [PATCH] `wrap` dispatch moved and `FunctionModel` docstrings

---
 src/types/base.jl | 21 ++++++++++++++++++++-
 src/utils/base.jl | 45 ++++++++++++++++++++-------------------------
 2 files changed, 40 insertions(+), 26 deletions(-)

diff --git a/src/types/base.jl b/src/types/base.jl
index 832469f..4cf58f6 100644
--- a/src/types/base.jl
+++ b/src/types/base.jl
@@ -26,12 +26,13 @@ and enclose a *tree* of `AbstractModel`s (with `LeafModel`s at the leaves).
 - `isopen(m::AbstractModel)::Bool`
 - `apply(m::AbstractModel, i::AbstractInterpretation; kwargs...)`
 
-# Utility functions (requiring a walk of the tree)
+# Utility functions
 - `outcometype(m::AbstractModel)`
 - `outputtype(m::AbstractModel)`
 - `info(m::AbstractModel, key)`
 - `info!(m::AbstractModel, key)`
 - `hasinfo(m::AbstractModel, key)`
+- `wrap(m::AbstractModel)`
 
 # Examples
 TODO:
@@ -204,6 +205,22 @@ See also [`AbstractModel`](@ref), [`info`](@ref).
 """
 hasinfo(m::AbstractModel, key) = haskey(info(m), key)
 
+"""
+    wrap(o::Any)::AbstractModel
+
+This function wraps anything into an AbstractModel.
+The default behavior is the following:
+- when called on an `AbstractModel`, the model is simply returned
+(no wrapping is performed);
+- Function`s and `FunctionWrapper`s are wrapped into a [`FunctionModel`](@ref);
+- every other object is wrapped into a `ConstantModel`.
+
+See also [`AbstractModel`](@ref), [`ConstantModel`](@ref), [`FunctionModel`](@ref),
+[`LeafModel`](@ref).
+"""
+wrap(o::Any, FM::Type{<:AbstractModel}) = convert(FM, wrap(o))
+wrap(m::AbstractModel) = m
+
 ############################################################################################
 ##################################### LeafModel ############################################
 ############################################################################################
@@ -232,3 +249,5 @@ true
 See also [`AbstractModel`](@ref), [`ConstantModel`](@ref), [`FunctionModel`](@ref).
 """
 abstract type LeafModel{O} <: AbstractModel{O} end
+
+LeafModel(o) = wrap(o)
diff --git a/src/utils/base.jl b/src/utils/base.jl
index c8c1546..af6e201 100644
--- a/src/utils/base.jl
+++ b/src/utils/base.jl
@@ -79,6 +79,8 @@ apply(
     kwargs...
 ) = Fill(outcome(m), ninstances(d))
 
+wrap(o::O) where {O} = convert(ConstantModel{O}, o)
+
 convert(::Type{ConstantModel{O}}, o::O) where {O} = ConstantModel{O}(o)
 convert(::Type{<:AbstractModel{F}}, m::ConstantModel) where {F} = ConstantModel{F}(m)
 
@@ -92,13 +94,15 @@ convert(::Type{<:AbstractModel{F}}, m::ConstantModel) where {F} = ConstantModel{
         info::NamedTuple
     end
 
-A `FunctionModel` is a `LeafModel` that applies a native Julia `Function`
-in order to compute the outcome. Over efficiency concerns, it is mandatory to make explicit
-the output type `O` by wrapping the `Function` into an object of type
-`FunctionWrapper{O}`
-(see [FunctionWrappers](https://github.com/yuyichao/FunctionWrappers.jl).
+A `FunctionModel` is a `LeafModel` that applies a native Julia `Function` in order to
+compute the outcome.
 
-See also [`ConstantModel`](@ref), [`LeafModel`](@ref).
+!!! warning
+    Over efficiency concerns, it is mandatory to make explicit the output type `O` by
+    wrapping the `Function` into an object of type `FunctionWrapper{O}`
+    (see [FunctionWrappers](https://github.com/yuyichao/FunctionWrappers.jl).
+
+See also [`LeafModel`](@ref).
 """
 struct FunctionModel{O} <: LeafModel{O}
     f::FunctionWrapper{O}
@@ -149,8 +153,18 @@ struct FunctionModel{O} <: LeafModel{O}
     end
 end
 
+"""
+    f(m::FunctionModel)
+
+Getter for the `FunctionWrapper` within `m`.
+
+See also [`FunctionModel`](@ref),
+[FunctionWrappers](https://github.com/yuyichao/FunctionWrappers.jl).
+"""
 f(m::FunctionModel) = m.f
+
 isopen(::FunctionModel) = false
+
 function apply(
     m::FunctionModel,
     i::AbstractInterpretation;
@@ -181,27 +195,8 @@ end
 
 convert(::Type{<:AbstractModel{F}}, m::FunctionModel) where {F} = FunctionModel{F}(m)
 
-"""
-    wrap(o::Any)::AbstractModel
-
-This function wraps anything into an AbstractModel.
-The default behavior is the following:
-- when called on an `AbstractModel`, the model is
-simply returned (no wrapping is performed);
-- `Function`s and `FunctionWrapper`s are wrapped into a `FunctionModel`;
-- every other object is wrapped into a `ConstantModel`.
-
-See also
-[`ConstantModel`](@ref), [`FunctionModel`](@ref), [`LeafModel`](@ref).
-"""
-wrap(o::Any, FM::Type{<:AbstractModel}) = convert(FM, wrap(o))
-wrap(m::AbstractModel) = m
 wrap(o::Function) = FunctionModel(o)
 wrap(o::FunctionWrapper{O}) where {O} = FunctionModel{O}(o)
-wrap(o::O) where {O} = convert(ConstantModel{O}, o)
-
-# Helper
-LeafModel(o) = wrap(o)
 
 ############################################################################################
 ############################################################################################