documentation

4 files changed, 136 insertions, 9 deletions

diff --git a/src/main/scala/scalam/m/ast/Identifier.scala b/src/main/scala/scalam/m/ast/Identifier.scala
index 87bfa43..6778e74 100644
--- a/src/main/scala/scalam/m/ast/Identifier.scala
+++ b/src/main/scala/scalam/m/ast/Identifier.scala
@@ -1,13 +1,19 @@
 package scalam.m.ast
 
-case class Identifier(name: String) extends Mable{
-  
+/**
+ * A matlab identifier.
+ * @name name of variable (this must be a valid matlab identifier string)
+ *
+ * @define construct identifier
+ */
+case class Identifier(name: String) extends Mable {
+
   def m = name
-  
+
   def toValid = {
     val word = name.filter(c => c.isLetterOrDigit || c == '_')
     val id = word.headOption match {
-      case None => sys.error("")
+      case None => "x"
       case Some(c) => if (!c.isLetter) 'x' + word else word
     }
     Identifier(id)
diff --git a/src/main/scala/scalam/m/ast/expressions.scala b/src/main/scala/scalam/m/ast/expressions.scala
index db99ae6..81e048e 100644
--- a/src/main/scala/scalam/m/ast/expressions.scala
+++ b/src/main/scala/scalam/m/ast/expressions.scala
@@ -1,6 +1,10 @@
 package scalam.m.ast
 
-trait Expression extends Mable with Root{
+/**
+ * Represents a matlab expression.
+ * @define construct expression
+ */
+trait Expression extends Mable with Root {
   def m: String = this match {
     case IntLiteral(x) => x.toString
     case DoubleLiteral(x) => x.toString
@@ -18,13 +22,77 @@ trait Expression extends Mable with Root{
   }
 }
 
+/**
+ * A matlab integer literal.
+ * @define construct integer literal
+ */
 case class IntLiteral(x: Int) extends Expression
+
+/**
+ * A matlab double literal.
+ * @define construct double literal
+ */
 case class DoubleLiteral(x: Double) extends Expression
+
+/**
+ * A matlab string literal.
+ * @define construct string literal
+ */
 case class StringLiteral(x: String) extends Expression
+
+/**
+ * The matlab slice literal (:).
+ * @define construct slice literal
+ */
 case object SliceLiteral extends Expression
+
+/**
+ * A matlab array or single-line matrix literal.
+ * @param elements elements of the array
+ *
+ * @define construct array literal
+ */
 case class ArrayLiteral(elements: Expression*) extends Expression
+
+/**
+ * A matlab matrix literal.
+ * @param rows rows of the matrix
+ *
+ * @define construct matrix literal
+ */
 case class MatrixLiteral(rows: Expression*) extends Expression
+
+/**
+ * A matlab variable access.
+ * @param id identifier ("variable name") of the variable
+ *
+ * @define construct variable access
+ */
 case class Variable(id: Identifier) extends Expression
+
+/**
+ * A matlab matrix access by index.
+ * @param id identifier of the variable to index
+ * @param indices indices
+ *
+ * @define construct matrix access by index
+ */
 case class IndexMatrix(id: Identifier, indices: Expression*) extends Expression
+
+/**
+ * A matlab structure access by index.
+ * @param id identifier of the variable to index
+ * @param indices indices
+ *
+ * @define construct structure access by index
+ */
 case class IndexStructure(id: Identifier, indices: Expression*) extends Expression
+
+/**
+ * A matlab function call.
+ * @param function identifier of the function
+ * @param params parameters to pass to function call
+ *
+ * @define construct function call
+ */
 case class Function(function: Identifier, params: Expression*) extends Expression
\ No newline at end of file
diff --git a/src/main/scala/scalam/m/ast/package.scala b/src/main/scala/scalam/m/ast/package.scala
index c4ab291..5eb5c83 100644
--- a/src/main/scala/scalam/m/ast/package.scala
+++ b/src/main/scala/scalam/m/ast/package.scala
@@ -1,20 +1,40 @@
 package scalam.m.ast
 
-/** Trait common to all objects having a representation in the matlab programming language. */
+/**
+ * Trait common to all objects having a representation in the matlab programming language.
+ * @define construct construct
+ */
 trait Mable {
+
+  /** Generates the matlab code associated to this $construct. */
   def m: String
 }
 
+/**
+ * Root (ie self-contained/top-level) syntactic elements of the matlab language inherit from this trait.
+ * A root element in the matlab language is an element that may be contained on one line and optionally be terminated by a semi-colon.
+ * Currently a root element is either a statement (assigment, etc...), a comment or an expression that is evaluated.
+ */
 trait Root {
+
+  /** Returns the matlab code of this root element. */
   final def line: String = this match {
     case statement: Statement => statement.m + ";"
     case expression: Expression => expression.m + ";"
     case comment: Comment => comment.m
   }
-  
+
+  /**
+   * Utility function to associate this root with and end-of-line comment.
+   * Calling `line` on the root element returned by this method, will forward the call to `this.line` and append a comment.
+   */
   def withComment(comment: Comment) = EOLComment(this, comment)
 }
 
+/**
+ * Represents a matlab comment.
+ * @define construct comment
+ */
 trait Comment extends Mable with Root {
   def m = this match {
     case SimpleComment(text) => "% " + text
@@ -23,8 +43,21 @@ trait Comment extends Mable with Root {
   }
 }
 
+/**
+ * Represents a simple matlab comment. This type of comment begins with a single percent sign (%).
+ * @define construct simple comment
+ */
 case class SimpleComment(text: String) extends Comment
+
+/**
+ * Represents a double matlab comment. This type of comment begins with a double percent sign (%%).
+ * @define construct double comment
+ */
 case class DoubleComment(text: String) extends Comment
+
+/**
+ * Represents an end-of-line comment associated to another matlab root element (such as a statement).
+ */
 case class EOLComment(root: Root, comment: Comment) extends Comment
 
 
diff --git a/src/main/scala/scalam/m/ast/statements.scala b/src/main/scala/scalam/m/ast/statements.scala
index 97b9821..5c39fb9 100644
--- a/src/main/scala/scalam/m/ast/statements.scala
+++ b/src/main/scala/scalam/m/ast/statements.scala
@@ -1,14 +1,34 @@
 package scalam.m.ast
 
-trait Statement extends Mable with Root{
+/**
+ * A matlab statement.
+ * @define construct statement
+ */
+trait Statement extends Mable with Root {
   def m: String = this match {
     case Assign(id, value) => id.m + " = " + value.m
     case AssignMatrixIndex(id, indices, value) =>
       id.m + indices.map(_.m).mkString("(", ",", ")") + " = " + value.m
-    
+
     case _ => throw new IllegalArgumentException("unkown statement: " + this)
   }
 }
 
+/**
+ * Variable assignment.
+ * @param variable identifer of variable
+ * @param value value to assign
+ *
+ * @define construct assignment
+ */
 case class Assign(variable: Identifier, value: Expression) extends Statement
+
+/**
+ * Variable (matrix) index assignment.
+ * @param variable identifer of variable
+ * @param indices indices of variable
+ * @param value value to assign
+ *
+ * @define construct variable (matrix) assignment
+ */
 case class AssignMatrixIndex(variable: Identifier, indices: Seq[Expression], value: Expression) extends Statement