more doc refinements

Author: ablaom

src/fit_update.jl

@@ -39,12 +39,10 @@ overloaded to return `true`.
 
 The signature must include `verbosity` with `1` as default.
 
-If `data` encapsulates a *target* variable, as defined in LearnAPI.jl documentati[on, then
-[`LearnAPI.target(data)`](@ref) must be overloaded to return it. If [`predict`](@ref) or
-[`transform`](@ref) are implemented and consume data, then
-[`LearnAPI.features(data)`](@ref) must return something that can be passed as data to
-these methods. A fallback returns `first(data)` if `data` is a tuple, and `data`
-otherwise.
+If `data` encapsulates a *target* variable, as defined in LearnAPI.jl documentation, then
+[`LearnAPI.target`](@ref) must be implemented. If [`predict`](@ref) or [`transform`](@ref)
+are implemented and consume data, then you made need to overload
+[`LearnAPI.features`](@ref).
 
 The LearnAPI.jl specification has nothing to say regarding `fit` signatures with more than
 two arguments. For convenience, for example, an implementation is free to implement a

src/predict_transform.jl

@@ -98,8 +98,10 @@ implementation must be added to the list returned by
 [`LearnAPI.kinds_of_proxy(learner)`](@ref). List all available kinds of proxy by doing
 `LearnAPI.kinds_of_proxy()`.
 
-If `data` is not present in the implemented signature (eg., for density estimators) then
-[`LearnAPI.features(learner, data)`](@ref) must return `nothing`.
+When `predict` is implemented, it may be necessary to overload
+[`LearnAPI.features`](@ref). If `data` is not present in the implemented signature (eg.,
+for density estimators) then [`LearnAPI.features(learner, data)`](@ref) must always return
+`nothing`.
 
 $(DOC_IMPLEMENTED_METHODS(":(LearnAPI.predict)"))
 
@@ -161,7 +163,12 @@ See also [`fit`](@ref), [`predict`](@ref),
 # New implementations
 
 Implementation for new LearnAPI.jl learners is
-optional. $(DOC_IMPLEMENTED_METHODS(":(LearnAPI.transform)"))
+optional.
+
+When `predict` is implemented, it may be necessary to overload
+[`LearnAPI.features`](@ref).
+
+$(DOC_IMPLEMENTED_METHODS(":(LearnAPI.transform)"))
 
 $(DOC_SLURPING(:transform))
 

src/target_weights_features.jl

@@ -24,7 +24,7 @@ the LearnAPI.jl documentation.
 
 A fallback returns `nothing`. The method must be overloaded if [`fit`](@ref) consumes data
 that includes a target variable. If `obs` is not being overloaded, then `observations`
-above is any `data` supported in calls of the form [`fit(learner, data)`](@ref).  The form
+above is any `data` supported in calls of the form [`fit(learner, data)`](@ref). The form
 of the output `y` should be suitable for pairing with the output of [`predict`](@ref), in
 the evaluation of a loss function, for example.
 
@@ -93,11 +93,11 @@ The object `X` returned by `LearnAPI.features` has the same number of observatio
 
 A fallback returns `first(observations)` if `observations` is a tuple, and otherwise
 returns `observations`. New implementations may need to overload this method if this
-fallback is inadequate.
+fallback is inadequate. 
 
 For density estimators, whose `fit` typically consumes *only* a target variable, you
-should overload this method to return `nothing`.  If `obs` is not being overloaded, then
-`observations` above is any `data` supported in calls of the form [`fit(learner,
+should overload this method to always return `nothing`.  If `obs` is not being overloaded,
+then `observations` above is any `data` supported in calls of the form [`fit(learner,
 data)`](@ref).
 
 It must otherwise be possible to pass the return value `X` to `predict` and/or