add @functions and have LearnAPI.functions() return accessors

Author: ablaom

README.md

@@ -22,9 +22,8 @@ julia> ridge = Ridge(lambda=0.1)
 Inspect available functionality:
 
 ```
-julia> LearnAPI.functions(ridge)
-(:(LearnAPI.fit), :(LearnAPI.learner), :(LearnAPI.strip), :(LearnAPI.obs), 
-:(LearnAPI.features), :(LearnAPI.target), :(LearnAPI.predict), :(LearnAPI.coefficients))
+julia> @functions ridge
+(fit, LearnAPI.learner, LearnAPI.strip, obs, LearnAPI.features, LearnAPI.target, predict, LearnAPI.coefficients
 ```
 
 Train:

docs/src/index.md

@@ -55,7 +55,7 @@ y = <some training target>
 Xnew = <some test or production features>
 
 # List LearnaAPI functions implemented for `forest`:
-LearnAPI.functions(forest)
+@functions forest
 
 # Train:
 model = fit(forest, X, y)

docs/src/reference.md

@@ -199,8 +199,9 @@ minimal (but useless) implementation, see the implementation of `SmallLearner`
 ## Utilities
 
 ```@docs
+@functions
 LearnAPI.clone
-LearnAPI.@trait
+@trait
 ```
 
 ---

src/LearnAPI.jl

@@ -11,7 +11,7 @@ include("accessor_functions.jl")
 include("traits.jl")
 include("clone.jl")
 
-export @trait
+export @trait, @functions
 export fit, update, update_observations, update_features
 export predict, transform, inverse_transform, obs
 

src/accessor_functions.jl

@@ -312,23 +312,23 @@ function training_labels end
 
 # :extras intentionally excluded:
 const ACCESSOR_FUNCTIONS_WITHOUT_EXTRAS = (
-    learner,
-    coefficients,
-    intercept,
-    tree,
-    trees,
-    feature_names,
-    feature_importances,
-    training_labels,
-    training_losses,
-    training_predictions,
-    training_scores,
-    components,
+    :(LearnAPI.learner),
+    :(LearnAPI.coefficients),
+    :(LearnAPI.intercept),
+    :(LearnAPI.tree),
+    :(LearnAPI.trees),
+    :(LearnAPI.feature_names),
+    :(LearnAPI.feature_importances),
+    :(LearnAPI.training_labels),
+    :(LearnAPI.training_losses),
+    :(LearnAPI.training_predictions),
+    :(LearnAPI.training_scores),
+    :(LearnAPI.components),
 )
 
 const ACCESSOR_FUNCTIONS_WITHOUT_EXTRAS_LIST = join(
     map(ACCESSOR_FUNCTIONS_WITHOUT_EXTRAS) do f
-    "[`LearnAPI.$f`](@ref)"
+    "[`$f`](@ref)"
     end,
     ", ",
     " and ",
@@ -354,11 +354,12 @@ $(DOC_IMPLEMENTED_METHODS(":(LearnAPI.training_labels)")).
 """
 function extras end
 
-const ACCESSOR_FUNCTIONS = (extras, ACCESSOR_FUNCTIONS_WITHOUT_EXTRAS...)
+const ACCESSOR_FUNCTIONS =
+    (:(LearnAPI.extras), ACCESSOR_FUNCTIONS_WITHOUT_EXTRAS...)
 
 const ACCESSOR_FUNCTIONS_LIST = join(
     map(ACCESSOR_FUNCTIONS) do f
-    "[`LearnAPI.$f`](@ref)"
+    "[`$f`](@ref)"
     end,
     ", ",
     " and ",

src/traits.jl

@@ -65,12 +65,18 @@ with `learner`, or an associated model (object returned by `fit(learner, ...)`,
 first argument. Learner traits (methods for which `learner` is the *only* argument)
 are excluded.
 
+To return actual functions, instead of symbols, use [`@functions`](@ref)` learner`
+instead.
+
 The returned tuple may include expressions like `:(DecisionTree.print_tree)`, which
 reference functions not owned by LearnAPI.jl.
 
 The understanding is that `learner` is a LearnAPI-compliant object whenever the return
 value is non-empty.
 
+Do `LearnAPI.functions()` to list all possible elements of the return value owned by
+LearnAPI.jl.
+
 # Extended help
 
 # New implementations
@@ -100,6 +106,7 @@ learner-specific ones. The LearnAPI.jl accessor functions are: $ACCESSOR_FUNCTIO
 (`LearnAPI.strip` is always included).
 
 """
+functions(::Any) = ()
 functions() = (
     :(LearnAPI.fit),
     :(LearnAPI.learner),
@@ -114,8 +121,34 @@ functions() = (
     :(LearnAPI.predict),
     :(LearnAPI.transform),
     :(LearnAPI.inverse_transform),
+    ACCESSOR_FUNCTIONS...,
 )
-functions(::Any) = ()
+
+"""
+    @functions learner
+
+Return a tuple of functions that can be meaningfully applied with `learner`, or an
+associated model, as the first argument. An "associated model" is an object returned by
+`fit(learner, ...)`. Learner traits (methods for which `learner` is the *only* argument)
+are excluded.
+
+```
+julia> @functions my_feature_selector
+(fit, LearnAPI.learner, strip, obs, transform)
+
+```
+
+New learner implementations should overload [`LearnAPI.functions`](@ref).
+
+See also [`LearnAPI.functions`](@ref).
+
+"""
+macro functions(learner)
+    quote
+        exs = LearnAPI.functions(learner)
+        eval.(exs)
+    end |> esc
+end
 
 """
     LearnAPI.kinds_of_proxy(learner)