Give more flesh to the docs.

src/activations.rs

@@ -2,13 +2,19 @@
 
 use num::{Float, one, zero};
 
+/// Wraps two functions or closures as an activation function that can be
+/// used by a network.
 pub struct ActivationFunction<F, V, D>
     where F: Float,
           V: Fn(F) -> F,
           D: Fn(F) -> F
 {
     _marker: ::std::marker::PhantomData<F>,
+    /// Mathematical definition of the activation function, to be evaluated
+    /// at any point.
     pub value: V,
+    /// Mathematical derivative of the activation function, to be evaluated
+    /// at any point.
     pub derivative: D
 }
 
@@ -17,11 +23,7 @@ impl<F, V, D> ActivationFunction<F, V, D>
           V: Fn(F) -> F,
           D: Fn(F) -> F
 {
-    /// Wraps the two provided functions or closures as an activation function
-    /// that can be used by a network.
-    ///
-    /// The second function is supposed to be the mathematical derivative of the
-    /// first one, and most of the algorithms rely on that.
+    /// Create an `ActivationFunction` out of two functions or closures.
     pub fn new(value: V, derivative: D) -> ActivationFunction<F, V, D> {
         ActivationFunction {
             _marker: ::std::marker::PhantomData,

src/lib.rs

@@ -22,9 +22,11 @@ pub mod util;
 ///
 /// This computation is not supposed to alter the internal state of the object.
 pub trait Compute<F: Float>{
-    /// Process input into output
+    /// Process input into output.
     fn compute(&self, input: &[F]) -> Vec<F>;
+    /// The number of inputs this network expects.
     fn input_size(&self) -> usize;
+    /// The number of outputs generated by this network.
     fn output_size(&self) -> usize;
 }
 
@@ -36,18 +38,26 @@ pub trait Method {}
 /// A trait for networks that can be trained using a certain method of
 /// unsupervised training.
 pub trait UnsupervisedTrain<F: Float, M: Method> {
+    /// Performs one step of unsupervised training on given input using
+    /// the learning parameters defined by `rule`.
     fn unsupervised_train(&mut self, rule: &M, input: &[F]);
 }
 
 /// A trait for networks that can be trained using a certain method of
 /// supervised training.
 pub trait SupervisedTrain<F: Float, M: Method> {
+    /// Performs one step of supervised training on given input and target
+    /// value using the learning parameters defined by `rule`.
     fn supervised_train(&mut self, rule: &M, input: &[F], target: &[F]);
 }
 
 /// A trait for networks that can be trained using a certain method in a
 /// back-propagation way: the training returns a values vector that is
 /// to be used as a target value for the previous layer.
 pub trait BackpropTrain<F: Float, M: Method> {
+    /// Performs one step of supervised training on given input and target
+    /// value using the learning parameters defined by `rule`.
+    ///
+    /// Returns the value to feed to the previous layer.
     fn backprop_train(&mut self, rule: &M, input: &[F], target: &[F]) -> Vec<F>;
 }

src/training.rs

@@ -10,6 +10,10 @@ use Method;
 /// The gradient descend approach, consisting on finding a minimum of the
 /// error by going down its gradient.
 pub struct GradientDescent<F: Float> {
+    /// The learning rate associated with this gradient descent rule.
+    ///
+    /// A very small value will make the training slow, but a too big one
+    /// will make it unstable.
     pub rate: F
 }
 
@@ -18,6 +22,10 @@ impl<F: Float> Method for GradientDescent<F> {}
 /// The perceptron rule, a classic learning rule for one-layered
 /// feedforward networks.
 pub struct PerceptronRule<F: Float> {
+    /// The learning rate associated with this perceptron rule.
+    ///
+    /// A very small value will make the training slow, but a too big one
+    /// will make it unstable.
     pub rate: F
 }
 

src/util.rs

@@ -155,6 +155,8 @@ pub struct FixedOutput<F: Float> {
 }
 
 impl<F: Float> FixedOutput<F> {
+    /// Creates a new fixed output network that will always return the
+    /// values provided as `output`.
     pub fn new(output: &[F]) -> FixedOutput<F> {
         FixedOutput { output: output.to_owned() }
     }