add documentation

7 files changed, 89 insertions, 7 deletions

diff --git a/src/main/scala/scalam/LowPriorityImplicits.scala b/src/main/scala/scalam/LowPriorityImplicits.scala
index 4eec21a..6014053 100644
--- a/src/main/scala/scalam/LowPriorityImplicits.scala
+++ b/src/main/scala/scalam/LowPriorityImplicits.scala
@@ -3,9 +3,19 @@ package scalam
 import breeze.linalg.DenseVector
 import scalam.collection._
 
+/** Defines implicit conversions with a lower priority than those found in [[scalam]]'s package object.*/
 trait LowPriorityImplicits {
-  
+
+  /**
+   * Wraps the given dense vector to a sequence.
+   * @see scalam.collection.WrappedDenseVector
+   */
   implicit def wrapDenseVector[A: ClassManifest](v: DenseVector[A]) = new WrappedDenseVector(v)
+
+  /**
+   * Unwraps the given wrapped dense vector to a normal dense vector.
+   * @see scalam.collection.WrappedDenseVector
+   */
   implicit def unwrapDenseVector[A: ClassManifest](w: WrappedDenseVector[A]) = w.self
-  
+
 }
\ No newline at end of file
diff --git a/src/main/scala/scalam/collection/DenseVectorLike.scala b/src/main/scala/scalam/collection/DenseVectorLike.scala
index e34f05c..a2c3545 100644
--- a/src/main/scala/scalam/collection/DenseVectorLike.scala
+++ b/src/main/scala/scalam/collection/DenseVectorLike.scala
@@ -3,7 +3,17 @@ package scalam.collection
 import scala.collection.mutable.IndexedSeqLike
 import breeze.linalg.DenseVector
 
+/** A common supertrait of `DenseVectorOps` and `WrappedDenseVector` that factors out most
+* operations on dense vectors and wrapped dense vectors.
+*
+* @tparam Elem type of the elements contained in the dense vector like object.
+* @tparam Repr the type of the actual collection containing the elements.
+*
+* @define Coll `DenseVectorLike`
+*/
 trait DenseVectorLike[Elem, Repr] extends IndexedSeqLike[Elem, Repr]{
+  
+  /** Underlying dense vector. */
   def self: DenseVector[Elem]
   
   override def apply(index: Int): Elem = self.apply(index)
diff --git a/src/main/scala/scalam/collection/DenseVectorOps.scala b/src/main/scala/scalam/collection/DenseVectorOps.scala
index da33d5d..ace37a3 100644
--- a/src/main/scala/scalam/collection/DenseVectorOps.scala
+++ b/src/main/scala/scalam/collection/DenseVectorOps.scala
@@ -5,15 +5,37 @@ import scala.collection.mutable.ArrayBuffer
 import scala.collection.generic.CanBuildFrom
 import scala.collection.mutable.Builder
 
+/**
+ * This class serves as a wrapper for `breeze.linalg.DenseVector`s with all the operations found in
+ * indexed sequences. Where needed, instances of DenseVectors are implicitly converted
+ * into this class.
+ *
+ * The difference between this class and `WrappedDenseVector` is that calling transformer
+ * methods such as `filter` and `map` will yield a `DenseVector`, whereas a `WrappedDenseVector`
+ * will remain a `WrappedDenseVector`.
+ *
+ * @see [[scala.collection.mutable.ArrayOps]]
+ *
+ * @tparam Elem type of the elements contained in this DenseVector.
+ *
+ * @define Coll `DenseVector`
+ * @define orderDependent
+ * @define orderDependentFold
+ * @define mayNotTerminateInf
+ * @define willNotTerminateInf
+ */
 class DenseVectorOps[Elem: ClassManifest](override val repr: DenseVector[Elem]) extends DenseVectorLike[Elem, DenseVector[Elem]] {
   val self = repr
   def newBuilder = DenseVectorOps.newBuilder[Elem]
-  
+
   override protected[this] def thisCollection = new WrappedDenseVector(self)
   override protected[this] def toCollection(repr: DenseVector[Elem]): WrappedDenseVector[Elem] = new WrappedDenseVector(repr)
   override def seq = thisCollection
 }
 
+/**
+ * A companion object for DenseVectorsOps.
+ */
 object DenseVectorOps {
-  def newBuilder[Elem: ClassManifest] = new ArrayBuffer[Elem]  mapResult (x => new DenseVector(x.toArray))
+  def newBuilder[Elem: ClassManifest] = new ArrayBuffer[Elem] mapResult (x => new DenseVector(x.toArray))
 }
diff --git a/src/main/scala/scalam/collection/WrappedDenseVector.scala b/src/main/scala/scalam/collection/WrappedDenseVector.scala
index 36926d9..0e49c07 100644
--- a/src/main/scala/scalam/collection/WrappedDenseVector.scala
+++ b/src/main/scala/scalam/collection/WrappedDenseVector.scala
@@ -6,10 +6,30 @@ import scala.collection.mutable.Builder
 import scala.collection.generic.CanBuildFrom
 import scala.collection.mutable.ArrayBuffer
 
+/**
+ * This class serves as a wrapper augmenting `breeze.linalg.DenseVector`s with all the operations
+ * found in indexed sequences.
+ *
+ * The difference between this class and `DenseVectorOps` is that calling transformer
+ * methods such as `filter` and `map` will yield an object of type `WrappedDenseVector`
+ * rather than a `DenseVector`.
+ *
+ * @see [[scala.collection.mutable.WrappedArray]]
+ * 
+ * @tparam Elem type of the elements contained in this WrappedDenseVector.
+ *
+ * @param self a dense vector contained within this wrapped dense vector
+ *
+ * @define Coll `DenseVector`
+ * @define coll dense vector
+ */
 class WrappedDenseVector[Elem: ClassManifest](val self: DenseVector[Elem]) extends IndexedSeq[Elem] with DenseVectorLike[Elem, WrappedDenseVector[Elem]] {
   override protected[this] def newBuilder: Builder[Elem, WrappedDenseVector[Elem]] = WrappedDenseVector.newBuilder[Elem]
 }
 
+/**
+ * A companion object for wrapped dense vectors.
+ */
 object WrappedDenseVector {
   def newBuilder[Elem: ClassManifest] = (new ArrayBuffer[Elem]) mapResult (x => new WrappedDenseVector(DenseVector(x.toArray)))
 
diff --git a/src/main/scala/scalam/collection/package.scala b/src/main/scala/scalam/collection/package.scala
new file mode 100644
index 0000000..391521c
--- /dev/null
+++ b/src/main/scala/scalam/collection/package.scala
@@ -0,0 +1,7 @@
+package scalam
+
+/**
+ * Provides classes for facilitating the integration of pre-existing collection-like structures into the standard scala collections framework.
+ * This package notably uses the WrappedColl and CollOps paradigm to integrate an external collection-like structure Coll into the collections framework, as is done in scala for arrays and strings.
+ */
+package object collection
\ No newline at end of file
diff --git a/src/main/scala/scalam/package.scala b/src/main/scala/scalam/package.scala
index 95f1fa2..6a167eb 100644
--- a/src/main/scala/scalam/package.scala
+++ b/src/main/scala/scalam/package.scala
@@ -3,14 +3,27 @@ import scalam.collection._
 import scala.collection.generic.CanBuildFrom
 import scala.collection.mutable.Builder
 
+/**
+ * A number of commonly applied implicit conversions are defined here, and
+ * in the parent type [[scalam.LowPriorityImplicits]]. Implicit conversions
+ * are provided for the integration of external collection-like structures into
+ * the standard Scala collections framework.
+ */
 package object scalam extends LowPriorityImplicits {
-  
+
+  /**
+   * Augments a given dense vector to a DenseVectorOps object, thereby providing it with all the methods found in sequences.
+   * @see scalam.collection.DenseVectorOps
+   */
   implicit def denseVector2Ops[A: ClassManifest](v: DenseVector[A]) = new DenseVectorOps(v)
 
+  /**
+   * Enables new dense vectors to be built from existing dense vectors. This implicit is used by [[scalam.collection.DenseVectorOps]].
+   */
   implicit def denseVectorCanBuildFrom[A: ClassManifest]: CanBuildFrom[DenseVector[_], A, DenseVector[A]] =
     new CanBuildFrom[DenseVector[_], A, DenseVector[A]] {
       def apply(from: DenseVector[_]): Builder[A, DenseVector[A]] = apply()
       def apply(): Builder[A, DenseVector[A]] = collection.DenseVectorOps.newBuilder[A]
     }
-  
+
 }
\ No newline at end of file
diff --git a/src/main/scala/scalam/plotting/FontSize.scala b/src/main/scala/scalam/plotting/FontSize.scala
index cbc0bef..a858e77 100644
--- a/src/main/scala/scalam/plotting/FontSize.scala
+++ b/src/main/scala/scalam/plotting/FontSize.scala
@@ -2,6 +2,6 @@ package scalam.plotting
 
 /**
  * Helper class used for implicit font size specification. Although a font size is typically represented by an Int,
- * a custom class is used as to avoid code pollution if using implicits.
+ * a custom class is used as to avoid code pollution when using implicits.
  */
 case class FontSize(fontSize: Int)
\ No newline at end of file