1 files changed, 35 insertions, 2 deletions
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