more doc tweaks

Author: ablaom

docs/src/anatomy_of_an_implementation.md

@@ -166,8 +166,8 @@ predictions.
 ## Algorithm traits
 
 Algorithm [traits](@ref traits) record extra generic information about an algorithm, or
-make specific promises of behavior. They usually have an algorithm as the single
-argument. We regard [`LearnAPI.constructor`](@ref) defined above as a trait.
+make specific promises of behavior. They usually have an algorithm as the single argument,
+and so we also regard [`LearnAPI.constructor`](@ref) defined above as a trait.
 
 In LearnAPI.jl `predict` always outputs a [target or target proxy](@ref proxy), where
 "target" is understood very broadly. We overload a trait to record the fact here that the
@@ -214,9 +214,10 @@ traits_list) to see which might apply to a new implementation, to enable maximum
 functionality provided by third party packages, and to assist third party algorithms that
 match machine learning algorithms to user-defined tasks.
 
-Having set `LearnAPI.target(::Ridge) == true` we are obliged to overload a multi-argument
-version of `LearnAPI.target` to extract the target from the `data` that gets supplied to
-`fit`:
+According to the contract articulated in its document string, having set
+[`LearnAPI.target(::Ridge)`](@ref) equal to `true`, we are obliged to overload a
+multi-argument version of `LearnAPI.target` to extract the target from the `data` that
+gets supplied to `fit`:
 
 ```@example anatomy
 LearnAPI.target(::Ridge, data) = last(data)

docs/src/index.md

@@ -12,9 +12,9 @@ A base Julia interface for machine learning and statistics </span>
 LearnAPI.jl is a lightweight, functional-style interface, providing a collection of
 [methods](@ref Methods), such as `fit` and `predict`, to be implemented by algorithms from
 machine learning and statistics. Through such implementations, these algorithms buy into
-functionality, such as hyperparameter optimization, as provided by ML/statistics toolboxes
-and other packages. LearnAPI.jl also provides a number of Julia [traits](@ref traits) for
-promising specific behavior.
+functionality, such as hyperparameter optimization and model composition, as provided by
+ML/statistics toolboxes and other packages. LearnAPI.jl also provides a number of Julia
+[traits](@ref traits) for promising specific behavior.
 
 ```@raw html
 &#128679;
@@ -78,7 +78,7 @@ opts out. The `fit` and `predict` methods consume these alternative representati
 The fallback data interface is the [MLUtils.jl](https://github.com/JuliaML/MLUtils.jl)
 `getobs/numobs` interface, and if the input consumed by the algorithm already implements
 that interface (tables, arrays, etc.) then overloading `obs` is completely optional. A
-plain iteration interface (to support, e.g., data loaders reading images from disk files)
+plain iteration interface (to support, e.g., data loaders reading images from disk)
 can also be specified.
 
 ## Learning more

docs/src/reference.md

@@ -54,16 +54,15 @@ compared with censored ground truth survival times.
 
 #### Definitions
 
-More generally, whenever we have a variable (e.g., a class label) that can (in principle)
-can be paired with a predicted value, or some predicted "proxy" for that variable (such as
-a class probability), then we call the variable a *target* variable, and the predicted
-output a *target proxy*. In this definition, it is immaterial whether or not the target
-appears in training (is supervised) or whether or not the model generalizes to new
+More generally, whenever we have a variable (e.g., a class label) that can, at least in
+principle, be paired with a predicted value, or some predicted "proxy" for that variable
+(such as a class probability), then we call the variable a *target* variable, and the
+predicted output a *target proxy*. In this definition, it is immaterial whether or not the
+target appears in training (is supervised) or whether or not the model generalizes to new
 observations ("learns").
 
 LearnAPI.jl provides singleton [target proxy types](@ref proxy_types) for prediction
-dispatch in LearnAPI.jl. These are also used to distinguish performance metrics provided
-by the package
+dispatch. These are also used to distinguish performance metrics provided by the package
 [StatisticalMeasures.jl](https://juliaai.github.io/StatisticalMeasures.jl/dev/).
 
 
@@ -151,8 +150,9 @@ Only these method names are exported by LearnAPI: `fit`, `transform`, `inverse_t
   [`LearnAPI.constructor`](@ref) and [`LearnAPI.functions`](@ref) are universally
   compulsory.
 
-- [`LearnAPI.target`](@ref) and [`LearnAPI.weights`](@ref) are both traits and methods to
-  extract, from `fit` input data, the target and per-observation weights, when available.
+- [`LearnAPI.target`](@ref) and [`LearnAPI.weights`](@ref) are traits which also include
+  extended signatures for extracting, from `fit` input data, the target and
+  per-observation weights, when available.
 
 ---