diff --git a/src/model_api.jl b/src/model_api.jl
index 8f452ec..3b33f9a 100644
--- a/src/model_api.jl
+++ b/src/model_api.jl
@@ -1,5 +1,7 @@
-# every model interface must implement a `fit` method of the form
-# `fit(model, verb::Integer, training_args...) -> fitresult, cache, report`
+"""
+every model interface must implement a `fit` method of the form
+`fit(model, verb::Integer, training_args...) -> fitresult, cache, report`
+"""
 function fit end
 
 # fallback for static transformations
@@ -12,23 +14,44 @@ fit(m::Supervised, verb::Integer, X, y, w) = fit(m, verb, X, y)
 # fitted parameters (eg, coeficients of linear model):
 fitted_params(::Model, fitres) = (fitresult=fitres,)
 
-# each model interface may overload the following refitting method:
+"""
+each model interface may overload the `update` refitting method
+"""
 update(m::Model, verb::Integer, fitres, cache, a...) = fit(m, verb, a...)
 
-# stub for online learning method update method
+"""
+each model interface may overload the `update_data` refitting method for online learning
+"""
 function update_data end
 
-# supervised methods must implement the predict operation; additionally,
-# probabilistic supervised models may overload one or more of
-# `predict_mode`, `predict_median` and `predict_mean`
+"""
+supervised methods must implement the `predict` operation
+"""
 function predict end
+
+"""
+probabilistic supervised models may overload `predict_mean`
+"""
 function predict_mean end
+
+"""
+probabilistic supervised models may overload `predict_mode`
+"""
 function predict_mode end
+
+"""
+probabilistic supervised models may overload `predict_median`
+"""
 function predict_median end
 
-# unsupervised methods must implement the transform operation and
-# may implement the inverse_transform operation
+"""
+unsupervised methods must implement the `transform` operation
+"""
 function transform end
+
+"""
+unsupervised methods may implement the `inverse_transform` operation
+"""
 function inverse_transform end
 
 # models can optionally overload these for enable serialization in a
@@ -36,5 +59,7 @@ function inverse_transform end
 function save end
 function restore end
 
-# operations implemented by some meta-models:
+"""
+some meta-models may choose to implement the `evaluate` operations
+"""
 function evaluate end