changeset 798:c24be8d4f6ab

Added documentation comments.
author Aziz K?ksal <aziz.koeksal@gmail.com>
date Sat, 01 Mar 2008 02:53:06 +0100
parents cf2ad5df025c
children fd719161e743
files trunk/src/Settings.d trunk/src/SettingsLoader.d trunk/src/dil/Location.d trunk/src/dil/Messages.d trunk/src/dil/SourceText.d trunk/src/dil/Time.d trunk/src/dil/lexer/Lexer.d trunk/src/dil/lexer/Token.d trunk/src/dil/lexer/TokensEnum.d trunk/src/dil/parser/ImportParser.d trunk/src/dil/parser/Parser.d trunk/src/dil/semantic/Interpreter.d trunk/src/dil/semantic/Module.d trunk/src/dil/semantic/Pass1.d trunk/src/dil/semantic/Pass2.d trunk/src/dil/semantic/Scope.d trunk/src/dil/semantic/Symbol.d trunk/src/dil/semantic/SymbolTable.d trunk/src/dil/semantic/Symbols.d trunk/src/dil/semantic/Types.d trunk/src/dil/semantic/TypesEnum.d trunk/src/dil/translator/German.d trunk/src/main.d
diffstat 23 files changed, 414 insertions(+), 283 deletions(-) [+]
line wrap: on
line diff
--- a/trunk/src/Settings.d	Fri Feb 29 22:51:24 2008 +0100
+++ b/trunk/src/Settings.d	Sat Mar 01 02:53:06 2008 +0100
@@ -21,9 +21,9 @@
   string[] importPaths;
   /// Array of DDoc macro file paths.
   string[] ddocFilePaths;
-  string xmlMapFile = "xml_map.d";
-  string htmlMapFile = "html_map.d";
-  string lexerErrorFormat = "{0}({1},{2})L: {3}";
-  string parserErrorFormat = "{0}({1},{2})P: {3}";
-  string semanticErrorFormat = "{0}({1},{2})S: {3}";
+  string xmlMapFile = "xml_map.d"; /// XML map file.
+  string htmlMapFile = "html_map.d"; /// HTML map file.
+  string lexerErrorFormat = "{0}({1},{2})L: {3}"; /// Lexer error.
+  string parserErrorFormat = "{0}({1},{2})P: {3}"; /// Parser error.
+  string semanticErrorFormat = "{0}({1},{2})S: {3}"; /// Semantic error.
 }
--- a/trunk/src/SettingsLoader.d	Fri Feb 29 22:51:24 2008 +0100
+++ b/trunk/src/SettingsLoader.d	Sat Mar 01 02:53:06 2008 +0100
@@ -17,9 +17,10 @@
 
 import tango.io.FilePath;
 
+/// Loads settings from a D module file.
 class SettingsLoader
 {
-  InfoManager infoMan;
+  InfoManager infoMan; /// Collects error messages.
   Module mod; /// Current module.
 
   this(InfoManager infoMan)
@@ -32,6 +33,10 @@
     return new SettingsLoader(infoMan);
   }
 
+  /// Creates an error report.
+  /// Params:
+  ///   token = where the error occurred.
+  ///   formatMsg = error message.
   void error(Token* token, char[] formatMsg, ...)
   {
     auto location = token.getErrorLocation();
@@ -136,6 +141,7 @@
   }
 }
 
+/// Loads an associative array from a D module file.
 class TagMapLoader : SettingsLoader
 {
   this(InfoManager infoMan)
@@ -174,6 +180,9 @@
   }
 }
 
+/// Resolves the path to a file from the executable's dir path
+/// if it is relative.
+/// Returns: filePath if it is absolute or execPath + filePath.
 string resolvePath(FilePath execPath, string filePath)
 {
   if ((new FilePath(filePath)).isAbsolute())
--- a/trunk/src/dil/Location.d	Fri Feb 29 22:51:24 2008 +0100
+++ b/trunk/src/dil/Location.d	Sat Mar 01 02:53:06 2008 +0100
@@ -3,31 +3,29 @@
   License: GPL3
 +/
 module dil.Location;
+
 import dil.lexer.Funcs;
 import dil.Unicode;
-import common;
 
+/// Represents a location in a source text.
 final class Location
 {
-  char[] filePath;
-  size_t lineNum;
-  char* lineBegin, to; /// Used to calculate column.
+  char[] filePath; /// The file path.
+  size_t lineNum; /// The line number.
+  char* lineBegin, to; /// Used to calculate the column.
 
+  /// Forwards the parameters to the second constructor.
   this(char[] filePath, size_t lineNum)
   {
     set(filePath, lineNum);
   }
 
+  /// Constructs a Location object.
   this(char[] filePath, size_t lineNum, char* lineBegin, char* to)
   {
     set(filePath, lineNum, lineBegin, to);
   }
 
-  Location clone()
-  {
-    return new Location(filePath, lineNum, lineBegin, to);
-  }
-
   void set(char[] filePath, size_t lineNum)
   {
     set(filePath, lineNum, null, null);
@@ -52,11 +50,9 @@
     this.filePath = filePath;
   }
 
-  /++
-    This is a primitive method to count the number of characters in a string.
-    Unicode compound characters and other special characters are not
-    taken into account.
-  +/
+  /// This is a primitive method to count the number of characters in a string.
+  /// Note: Unicode compound characters and other special characters are not
+  /// taken into account. The tabulator character is counted as one.
   uint calculateColumn()
   {
     uint col;
--- a/trunk/src/dil/Messages.d	Fri Feb 29 22:51:24 2008 +0100
+++ b/trunk/src/dil/Messages.d	Sat Mar 01 02:53:06 2008 +0100
@@ -3,9 +3,10 @@
   License: GPL3
 +/
 module dil.Messages;
+
 import common;
 
-/// Index into table of compiler messages.
+/// Enumeration of indices into the table of compiler messages.
 enum MID
 {
   // Lexer messages:
@@ -72,25 +73,29 @@
   HelpImportGraph,
 }
 
-private string[] messages;
+/// The table of compiler messages.
+private string[] g_compilerMessages;
 
 static this()
 {
-  messages = new string[MID.max+1];
+  g_compilerMessages = new string[MID.max+1];
 }
 
+/// Sets the compiler messages.
 void SetMessages(string[] msgs)
 {
   assert(MID.max+1 == msgs.length);
-  messages = msgs;
+  g_compilerMessages = msgs;
 }
 
+/// Returns the compiler message for mid.
 string GetMsg(MID mid)
 {
-  assert(mid < messages.length);
-  return messages[mid];
+  assert(mid < g_compilerMessages.length);
+  return g_compilerMessages[mid];
 }
 
+/// Returns a formatted string.
 char[] FormatMsg(MID mid, ...)
 {
   return Format(_arguments, _argptr, GetMsg(mid));
--- a/trunk/src/dil/SourceText.d	Fri Feb 29 22:51:24 2008 +0100
+++ b/trunk/src/dil/SourceText.d	Sat Mar 01 02:53:06 2008 +0100
@@ -18,6 +18,7 @@
   string filePath; /// The file path to the source text. Mainly used for error messages.
   char[] data; /// The UTF-8, zero-terminated source text.
 
+  /// Constructs a SourceText object.
   /// Params:
   ///   filePath = file path to the source file.
   ///   loadFile = whether to load the file in the constructor.
@@ -27,6 +28,7 @@
     loadFile && load();
   }
 
+  /// Constructs a SourceText object.
   /// Params:
   ///   filePath = file path for error messages.
   ///   data = memory buffer.
@@ -37,6 +39,7 @@
     addSentinelCharacter();
   }
 
+  /// Loads the source text from a file.
   void load(InfoManager infoMan = null)
   {
     if (!infoMan)
@@ -50,6 +53,7 @@
     addSentinelCharacter();
   }
 
+  /// Adds '\0' to the text (if not already there.)
   private void addSentinelCharacter()
   {
     if (data.length == 0 || data[$-1] != 0)
--- a/trunk/src/dil/Time.d	Fri Feb 29 22:51:24 2008 +0100
+++ b/trunk/src/dil/Time.d	Sat Mar 01 02:53:06 2008 +0100
@@ -7,9 +7,11 @@
 import tango.stdc.time : time_t, time, ctime;
 import tango.stdc.string : strlen;
 
+/// Some convenience functions for dealing with C's time functions.
 struct Time
 {
 static:
+  /// Returns the current date as a string.
   char[] toString()
   {
     time_t time_val;
@@ -19,16 +21,19 @@
     return timeStr.dup;
   }
 
+  /// Returns the time of timeStr: hh:mm:ss
   char[] time(char[] timeStr)
   {
     return timeStr[11..19];
   }
 
+  /// Returns the month and day of timeStr: Mmm dd
   char[] month_day(char[] timeStr)
   {
     return timeStr[4..10];
   }
 
+  /// Returns the year of timeStr: yyyy
   char[] year(char[] timeStr)
   {
     return timeStr[20..24];
--- a/trunk/src/dil/lexer/Lexer.d	Fri Feb 29 22:51:24 2008 +0100
+++ b/trunk/src/dil/lexer/Lexer.d	Sat Mar 01 02:53:06 2008 +0100
@@ -2480,7 +2480,7 @@
     error_(this.lineNum, this.lineBegin, columnPos, mid, _arguments, _argptr);
   }
 
-  /// Forwards error parameters.
+  /// ditto
   void error(uint lineNum, char* lineBegin, char* columnPos, MID mid, ...)
   {
     error_(lineNum, lineBegin, columnPos, mid, _arguments, _argptr);
--- a/trunk/src/dil/lexer/Token.d	Fri Feb 29 22:51:24 2008 +0100
+++ b/trunk/src/dil/lexer/Token.d	Sat Mar 01 02:53:06 2008 +0100
@@ -30,8 +30,8 @@
   /// Start of whitespace characters before token. Null if no WS.
   /// TODO: remove to save space; can be replaced by 'prev.end'.
   char* ws;
-  char* start; /// Start of token in source text.
-  char* end;   /// Points one past the end of token in source text.
+  char* start; /// Points to the first character of the token.
+  char* end;   /// Points one character past the end of the token.
 
   /// Data associated with this token.
   /// TODO: move data structures out; use only pointers here to keep Token.sizeof small.
@@ -45,11 +45,11 @@
       Token* tokLineNum; /// #line number
       Token* tokLineFilespec; /// #line number filespec
     }
-    /// For string tokens.
+    /// The value of a string token.
     struct
     {
-      string str; /// Zero-terminated string.
-      char pf; /// Postfix 'c', 'w', 'd' or 0 for none.
+      string str; /// Zero-terminated string. (The zero is included in the length.)
+      char pf;    /// Postfix 'c', 'w', 'd' or 0 for none.
     version(D2)
       Token* tok_str; /++ Points to the contents of a token string stored as a
                           doubly linked list. The last token is always '}' or
@@ -57,14 +57,14 @@
                       +/
     }
     Identifier* ident; /// For keywords and identifiers.
-    dchar  dchar_;
-    long   long_;
-    ulong  ulong_;
-    int    int_;
-    uint   uint_;
-    float  float_;
-    double double_;
-    real   real_;
+    dchar  dchar_;   /// A character value.
+    long   long_;    /// A long integer value.
+    ulong  ulong_;   /// An unsigned long integer value.
+    int    int_;     /// An integer value.
+    uint   uint_;    /// An unsigned integer value.
+    float  float_;   /// A float value.
+    double double_;  /// A double value.
+    real   real_;    /// A real value.
   }
 
   /// Returns the text of the token.
@@ -81,7 +81,8 @@
     return ws[0 .. start - ws];
   }
 
-  /// Find next non-whitespace token. Returns 'this' token if the next token is TOK.EOF or null.
+  /// Finds the next non-whitespace token.
+  /// Returns: 'this' token if the next token is TOK.EOF or null.
   Token* nextNWS()
   out(token)
   {
@@ -97,7 +98,8 @@
     return token;
   }
 
-  /// Find previous non-whitespace token. Returns 'this' token if the previous token is TOK.HEAD or null.
+  /// Finds the previous non-whitespace token.
+  /// Returns: 'this' token if the previous token is TOK.HEAD or null.
   Token* prevNWS()
   out(token)
   {
@@ -113,19 +115,20 @@
     return token;
   }
 
-  /// Returns the string for token kind tok.
-  static string toString(TOK tok)
+  /// Returns the string for a token kind.
+  static string toString(TOK kind)
   {
-    return tokToString[tok];
+    return tokToString[kind];
   }
 
-  /// Adds Flags. Whitespace to this token's flags.
+  /// Adds Flags.Whitespace to this.flags.
   void setWhitespaceFlag()
   {
     this.flags |= Flags.Whitespace;
   }
 
   /// Returns true if this is a token that can have newlines in it.
+  ///
   /// These can be block and nested comments and any string literal
   /// except for escape string literals.
   bool isMultiline()
@@ -271,6 +274,8 @@
     void* p = malloc(size);
     if (p is null)
       throw new OutOfMemoryException(__FILE__, __LINE__);
+    // TODO: Token.init should be all zeros.
+    // Maybe use calloc() to avoid this line?
     *cast(Token*)p = Token.init;
     return p;
   }
--- a/trunk/src/dil/lexer/TokensEnum.d	Fri Feb 29 22:51:24 2008 +0100
+++ b/trunk/src/dil/lexer/TokensEnum.d	Sat Mar 01 02:53:06 2008 +0100
@@ -6,6 +6,7 @@
 
 import common;
 
+/// Enumeration of token kinds.
 enum TOK : ushort
 {
   Invalid,
@@ -120,7 +121,7 @@
 alias TOK.FILE SpecialTokensBegin;
 alias TOK.VERSION SpecialTokensEnd;
 
-/// A table mapping each TOK to a string.
+/// A table that maps each token kind to a string.
 const string[TOK.MAX] tokToString = [
   "Invalid",
 
--- a/trunk/src/dil/parser/ImportParser.d	Fri Feb 29 22:51:24 2008 +0100
+++ b/trunk/src/dil/parser/ImportParser.d	Sat Mar 01 02:53:06 2008 +0100
@@ -14,6 +14,8 @@
 
 private alias TOK T;
 
+/// A light-weight parser which looks only for import statements
+/// in the source text.
 class ImportParser : Parser
 {
   this(SourceText srcText)
--- a/trunk/src/dil/parser/Parser.d	Fri Feb 29 22:51:24 2008 +0100
+++ b/trunk/src/dil/parser/Parser.d	Sat Mar 01 02:53:06 2008 +0100
@@ -33,22 +33,20 @@
 
   ImportDeclaration[] imports; /// ImportDeclarations in the source text.
 
-  // Attributes are evaluated in the parsing phase.
-  // Will probably be moved to class SemanticPass1.
+  /// Attributes are evaluated in the parsing phase.
+  /// TODO: will be removed. SemanticPass1 takes care of attributes.
   LinkageType linkageType;
-  Protection protection;
-  StorageClass storageClass;
-  uint alignSize = DEFAULT_ALIGN_SIZE;
-
-  private alias TOK T;
+  Protection protection; /// ditto
+  StorageClass storageClass; /// ditto
+  uint alignSize = DEFAULT_ALIGN_SIZE; /// ditto
+
+  private alias TOK T; /// Used often in this class.
   private alias TypeNode Type;
 
-  /++
-    Construct a Parser object.
-    Params:
-      text     = the UTF-8 source code.
-      infoMan  = used for collecting error messages.
-  +/
+  /// Constructs a Parser object.
+  /// Params:
+  ///   text     = the UTF-8 source code.
+  ///   infoMan  = used for collecting error messages.
   this(SourceText srcText, InfoManager infoMan = null)
   {
     this.infoMan = infoMan;
@@ -97,10 +95,9 @@
   uint trying; /// Greater than 0 if Parser is in try_().
   uint errorCount; /// Used to track nr. of errors while being in try_().
 
-  /++
-    This method executes the delegate parseMethod and when an error occurred
-    the state of the lexer and parser are restored.
-  +/
+  /// This method executes the delegate parseMethod and when an error occurred
+  /// the state of the lexer and parser are restored.
+  /// Returns: the return value of parseMethod().
   ReturnType try_(ReturnType)(ReturnType delegate() parseMethod, out bool success)
   {
     // Save members.
@@ -148,14 +145,14 @@
     return next.kind;
   }
 
-  /// Returns the token kind of the token after 'next'.
-  TOK peekAfter(ref Token* next)
+  /// Returns the token kind of the token that comes after t.
+  TOK peekAfter(ref Token* t)
   {
-    assert(next !is null);
+    assert(t !is null);
     do
-      lexer.peek(next);
-    while (next.isWhitespace) // Skip whitespace
-    return next.kind;
+      lexer.peek(t);
+    while (t.isWhitespace) // Skip whitespace
+    return t.kind;
   }
 
   /// Consumes the current token if its kind matches k and returns true.
@@ -188,12 +185,12 @@
     return set(new ModuleDeclaration(moduleFQN), begin);
   }
 
-  /++
-    Parse DeclarationDefinitions until the end of file is hit.
-    DeclDefs:
-      DeclDef
-      DeclDefs
-  +/
+  /// Parses DeclarationDefinitions until the end of file is hit.
+  /// $(PRE
+  /// DeclDefs :=
+  ///     DeclDef
+  ///     DeclDefs
+  /// )
   Declaration[] parseDeclarationDefinitions()
   {
     Declaration[] decls;
@@ -202,12 +199,12 @@
     return decls;
   }
 
-  /++
-    Parse the body of a template, class, interface, struct or union.
-    DeclDefsBlock:
-        { }
-        { DeclDefs }
-  +/
+  /// Parse the body of a template, class, interface, struct or union.
+  /// $(PRE
+  /// DeclDefsBlock :=
+  ///     { }
+  ///     { DeclDefs }
+  /// )
   CompoundDeclaration parseDeclarationDefinitionsBody()
   {
     // Save attributes.
@@ -236,6 +233,7 @@
     return decls;
   }
 
+  /// Parses a DeclarationDefinition.
   Declaration parseDeclarationDefinition()
   out(decl)
   { assert(isNodeSet(decl)); }
@@ -394,13 +392,14 @@
     return decl;
   }
 
-  /++
-    DeclarationsBlock:
-        : DeclDefs
-        { }
-        { DeclDefs }
-        DeclDef
-  +/
+  /// Parses a DeclarationsBlock.
+  /// $(PRE
+  /// DeclarationsBlock :=
+  ///     : DeclDefs
+  ///     { }
+  ///     { DeclDefs }
+  ///     DeclDef
+  /// )
   Declaration parseDeclarationsBlock(/+bool noColon = false+/)
   {
     Declaration d;
@@ -437,15 +436,13 @@
   //   return parseDeclarationsBlock(true);
   // }
 
-  /++
-    Parses either a VariableDeclaration or a FunctionDeclaration.
-    Params:
-      stc = previously parsed storage classes
-      protection = previously parsed protection attribute
-      linkType = previously parsed linkage type
-      testAutoDeclaration = whether to check for an AutoDeclaration
-      optionalParameterList = a hint for how to parse C-style function pointers
-  +/
+  /// Parses either a VariableDeclaration or a FunctionDeclaration.
+  /// Params:
+  ///   stc = previously parsed storage classes
+  ///   protection = previously parsed protection attribute
+  ///   linkType = previously parsed linkage type
+  ///   testAutoDeclaration = whether to check for an AutoDeclaration
+  ///   optionalParameterList = a hint for how to parse C-style function pointers
   Declaration parseVariableOrFunction(StorageClass stc = StorageClass.None,
                                       Protection protection = Protection.None,
                                       LinkageType linkType = LinkageType.None,
@@ -552,6 +549,7 @@
     return set(d, begin);
   }
 
+  /// Parses a variable initializer.
   Expression parseInitializer()
   {
     if (token.kind == T.Void)
@@ -1372,14 +1370,15 @@
     return type;
   }
 
-  /++
-    TemplateMixin:
-            mixin ( AssignExpression ) ;
-            mixin TemplateIdentifier ;
-            mixin TemplateIdentifier MixinIdentifier ;
-            mixin TemplateIdentifier !( TemplateArguments ) ;
-            mixin TemplateIdentifier !( TemplateArguments ) MixinIdentifier ;
-  +/
+  /// Parses a MixinDeclaration or MixinStatement.
+  /// $(PRE
+  /// TemplateMixin :=
+  ///         mixin ( AssignExpression ) ;
+  ///         mixin TemplateIdentifier ;
+  ///         mixin TemplateIdentifier MixinIdentifier ;
+  ///         mixin TemplateIdentifier !( TemplateArguments ) ;
+  ///         mixin TemplateIdentifier !( TemplateArguments ) MixinIdentifier ;
+  /// )
   Class parseMixin(Class)()
   {
   static assert(is(Class == MixinDeclaration) || is(Class == MixinStatement));
@@ -1429,6 +1428,7 @@
     return set(statements, begin);
   }
 
+  /// Parses a Statement.
   Statement parseStatement()
   {
     auto begin = token;
@@ -1665,23 +1665,24 @@
     return s;
   }
 
-  /++
-    ScopeStatement:
-        NoScopeStatement
-  +/
+  /// $(PRE
+  /// Parses a ScopeStatement.
+  /// ScopeStatement :=
+  ///     NoScopeStatement
+  /// )
   Statement parseScopeStatement()
   {
     return new ScopeStatement(parseNoScopeStatement());
   }
 
-  /++
-    NoScopeStatement:
-        NonEmptyStatement
-        BlockStatement
-    BlockStatement:
-        { }
-        { StatementList }
-  +/
+  /// $(PRE
+  /// NoScopeStatement :=
+  ///     NonEmptyStatement
+  ///     BlockStatement
+  /// BlockStatement :=
+  ///     { }
+  ///     { StatementList }
+  /// )
   Statement parseNoScopeStatement()
   {
     auto begin = token;
@@ -1705,11 +1706,11 @@
     return s;
   }
 
-  /++
-    NoScopeOrEmptyStatement:
-        ;
-        NoScopeStatement
-  +/
+  /// $(PRE
+  /// NoScopeOrEmptyStatement :=
+  ///     ;
+  ///     NoScopeStatement
+  /// )
   Statement parseNoScopeOrEmptyStatement()
   {
     if (consumed(T.Semicolon))
@@ -2232,6 +2233,7 @@
   |                         Assembler parsing methods                         |
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~+/
 
+  /// Parses an AsmBlockStatement.
   Statement parseAsmBlockStatement()
   {
     skip(T.Asm);
@@ -2672,6 +2674,7 @@
   |                        Expression parsing methods                         |
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~+/
 
+  /// Parses an Expression.
   Expression parseExpression()
   {
     alias parseAssignExpression parseNext;
@@ -3079,13 +3082,13 @@
     return e;
   }
 
-  /++
-    IdentifierExpression:
-            Identifier
-            TemplateInstance
-    TemplateInstance:
-            Identifier !( TemplateArguments )
-  +/
+  /// $(PRE
+  /// IdentifierExpression :=
+  ///         Identifier
+  ///         TemplateInstance
+  /// TemplateInstance :=
+  ///         Identifier !( TemplateArguments )
+  /// )
   Expression parseIdentifierExpression()
   {
     auto begin = token;
@@ -3406,6 +3409,7 @@
     return set(new NewExpression(/*e, */newArguments, type, ctorArguments), begin);
   }
 
+  /// Parses a Type.
   Type parseType()
   {
     return parseBasicType2(parseBasicType());
@@ -3515,6 +3519,8 @@
     assert(0);
   }
 
+  /// Returns true if the token after the closing parenthesis
+  /// is of kind tok.
   bool tokenAfterParenIs(TOK tok)
   {
     // We count nested parentheses tokens because template types
@@ -3548,7 +3554,7 @@
     return next.kind == tok;
   }
 
-  /// Parse the C-style array types after the declarator.
+  /// Parse the array types after the declarator (C-style.) E.g.: int a[]
   Type parseDeclaratorSuffix(Type lhsType)
   {
     // The Type chain should be as follows:
@@ -3672,12 +3678,12 @@
     return t;
   }
 
-  /++
-    Parse a list of AssignExpressions.
-    ExpressionList:
-      AssignExpression
-      AssignExpression , ExpressionList
-  +/
+  /// Parses a list of AssignExpressions.
+  /// $(PRE
+  /// ExpressionList :=
+  ///   AssignExpression
+  ///   AssignExpression , ExpressionList
+  /// )
   Expression[] parseExpressionList()
   {
     Expression[] expressions;
@@ -3687,11 +3693,12 @@
     return expressions;
   }
 
-  /++
-    Arguments:
-      ( )
-      ( ExpressionList )
-  +/
+  /// Parses a list of Arguments.
+  /// $(PRE
+  /// Arguments :=
+  ///   ( )
+  ///   ( ExpressionList )
+  /// )
   Expression[] parseArguments()
   {
     skip(T.LParen);
@@ -3702,6 +3709,7 @@
     return args;
   }
 
+  /// Parses a ParameterList.
   Parameters parseParameterList()
   out(params)
   {
@@ -3894,6 +3902,7 @@
   }
 } // version(D2)
 
+  /// Parses template parameters.
   void parseTemplateParameterList_(TemplateParameters tparams)
   {
     do
@@ -3981,12 +3990,9 @@
     } while (consumed(T.Comma))
   }
 
-  void expected(TOK tok)
-  {
-    if (token.kind != tok)
-      error(MID.ExpectedButFound, Token.toString(tok), token.srcText);
-  }
-
+  alias require expected;
+
+  /// Requires a token of kind tok.
   void require(TOK tok)
   {
     if (token.kind == tok)
@@ -3995,12 +4001,15 @@
       error(MID.ExpectedButFound, Token.toString(tok), token.srcText);
   }
 
+  /// Requires the next token to be of kind tok.
   void requireNext(TOK tok)
   {
     nT();
     require(tok);
   }
 
+  /// Optionally parses an identifier.
+  /// Returns: null or the identifier.
   Identifier* optionalIdentifier()
   {
     Identifier* id;
@@ -4019,8 +4028,10 @@
     return id;
   }
 
+  /// Reports an error if the current token is not an identifier.
   /// Params:
-  ///   errorMsg = an error that has no message ID yet.
+  ///   errorMsg = the error message to be used.
+  /// Returns: null or the identifier.
   Identifier* requireIdentifier(char[] errorMsg)
   {
     Identifier* id;
@@ -4031,6 +4042,10 @@
     return id;
   }
 
+  /// Reports an error if the current token is not an identifier.
+  /// Params:
+  ///   mid = the error message ID to be used.
+  /// Returns: null or the identifier.
   Identifier* requireIdentifier(MID mid)
   {
     Identifier* id;
@@ -4041,17 +4056,16 @@
     return id;
   }
 
+  /// Reports an error if the current token is not an identifier.
+  /// Returns: null or the token.
   Token* requireId()
   {
+    Token* idtok;
     if (token.kind == T.Identifier)
-    {
-      auto id = token;
-      nT();
-      return id;
-    }
+      (idtok = token), skip(T.Identifier);
     else
       error(MID.ExpectedButFound, "Identifier", token.srcText);
-    return null;
+    return idtok;
   }
 
   Token* requireIdToken(char[] errorMsg)
@@ -4060,7 +4074,11 @@
     if (token.kind == T.Identifier)
       (idtok = token), skip(T.Identifier);
     else
+    {
       error(token, errorMsg, token.srcText);
+      idtok = lexer.insertEmptyTokenBefore(token);
+      this.prevToken = idtok;
+    }
     return idtok;
   }
 
@@ -4073,17 +4091,22 @@
     return utf8Seq.length != 0;
   }
 
-  /// Reports an error that has no message ID yet.
+  /// Forwards error parameters.
   void error(Token* token, char[] formatMsg, ...)
   {
     error_(token, formatMsg, _arguments, _argptr);
   }
 
+  /// ditto
   void error(MID mid, ...)
   {
     error_(this.token, GetMsg(mid), _arguments, _argptr);
   }
 
+  /// Creates an error report and appends it to a list.
+  /// Params:
+  ///   token = used to get the location of where the error is.
+  ///   formatMsg = the compiler error message.
   void error_(Token* token, char[] formatMsg, TypeInfo[] _arguments, Arg _argptr)
   {
     if (trying)
--- a/trunk/src/dil/semantic/Interpreter.d	Fri Feb 29 22:51:24 2008 +0100
+++ b/trunk/src/dil/semantic/Interpreter.d	Sat Mar 01 02:53:06 2008 +0100
@@ -18,9 +18,10 @@
        dil.semantic.Types;
 import dil.Information;
 
+/// Used for compile-time evaluation of expressions.
 class Interpreter : Visitor
 {
-  Scope scop;
+  // Scope scop;
   InfoManager infoMan;
 
   static class Result : Expression
@@ -36,23 +37,27 @@
     NAR.type = Types.Error;
   }
 
-  static Expression interpret(Expression e, InfoManager infoMan, Scope scop)
+  /// Evaluates the expression e.
+  /// Returns: NAR or a value.
+  static Expression interpret(Expression e, InfoManager infoMan/+, Scope scop+/)
   {
-    return (new Interpreter(scop, infoMan)).start(e);
+    return (new Interpreter(/+scop,+/ infoMan)).eval(e);
   }
 
-  this(Scope scop, InfoManager infoMan)
+  /// Constructs an Interpreter object.
+  this(/+Scope scop, +/InfoManager infoMan)
   {
-    this.scop = scop;
+    // this.scop = scop;
     this.infoMan = infoMan;
   }
 
-  /// Start interpretation.
-  Expression start(Expression e)
+  /// Start evaluation.
+  Expression eval(Expression e)
   {
     return e;
   }
 
+  /// Returns true if e is immutable.
   bool isImmutable(Expression e)
   {
     switch (e.kind)
--- a/trunk/src/dil/semantic/Module.d	Fri Feb 29 22:51:24 2008 +0100
+++ b/trunk/src/dil/semantic/Module.d	Sat Mar 01 02:53:06 2008 +0100
@@ -23,24 +23,25 @@
 class Module : ScopeSymbol
 {
   SourceText sourceText; /// The source file of this module.
-  string moduleFQN; /// Fully qualified name of the module. E.g. dil.ast.Node
-  string packageName; /// E.g. dil.ast
-  string moduleName; /// E.g. Node
+  string moduleFQN; /// Fully qualified name of the module. E.g.: dil.ast.Node
+  string packageName; /// E.g.: dil.ast
+  string moduleName; /// E.g.: Node
 
   CompoundDeclaration root; /// The root of the parse tree.
   ImportDeclaration[] imports; /// ImportDeclarations found in this file.
   ModuleDeclaration moduleDecl; /// The optional ModuleDeclaration in this file.
   Parser parser; /// The parser used to parse this file.
 
-  Module[] modules;
+  // Module[] modules;
 
-  InfoManager infoMan;
+  InfoManager infoMan; /// Collects error messages.
 
   this()
   {
     super(SYM.Module, null, null);
   }
 
+  /// Constructs a Module object.
   /// Params:
   ///   filePath = file path to the source text; loaded in the constructor.
   ///   infoMan = used for collecting error messages.
@@ -52,11 +53,13 @@
     this.sourceText.load(infoMan);
   }
 
+  /// Returns the file path of the source text.
   string filePath()
   {
     return sourceText.filePath;
   }
 
+  /// Returns the file extension: "d" or "di".
   string fileExtension()
   {
     foreach_reverse(i, c; filePath)
@@ -65,12 +68,16 @@
     return "";
   }
 
+  /// Sets the parser to be used for parsing the source text.
   void setParser(Parser parser)
   {
     this.parser = parser;
   }
 
-  /// Starts the parser.
+  /// Parses the module.
+  /// Throws:
+  ///   An Exception if the there's no ModuleDeclaration and
+  ///   the file name is an invalid or reserved D identifier.
   void parse()
   {
     if (this.parser is null)
@@ -95,6 +102,7 @@
     }
   }
 
+  /// Returns the first token of the module's source text.
   Token* firstToken()
   {
     return parser.lexer.firstToken();
@@ -106,6 +114,8 @@
     return parser.errors.length || parser.lexer.errors.length;
   }
 
+  /// Returns a list of import paths.
+  /// E.g.: ["dil/ast/Node", "dil/semantic/Module"]
   string[] getImportPaths()
   {
     string[] result;
@@ -121,6 +131,7 @@
     return moduleFQN;
   }
 
+  /// Set's the module's FQN.
   void setFQN(string moduleFQN)
   {
     uint i = moduleFQN.length;
@@ -134,7 +145,7 @@
     this.moduleName = moduleFQN[(i == 0 ? 0 : i+1) .. $];
   }
 
-  /// Returns e.g. the FQN with slashes instead of dots.
+  /// Returns the module's FQN with slashes instead of dots.
   /// E.g.: dil/ast/Node
   string getFQNPath()
   {
--- a/trunk/src/dil/semantic/Pass1.d	Fri Feb 29 22:51:24 2008 +0100
+++ b/trunk/src/dil/semantic/Pass1.d	Sat Mar 01 02:53:06 2008 +0100
@@ -35,17 +35,18 @@
 {
   Scope scop; /// The current scope.
   Module modul; /// The module to be semantically checked.
-  CompilationContext context;
+  CompilationContext context; /// The compilation context.
 
   // Attributes:
-  LinkageType linkageType;
-  Protection protection;
-  StorageClass storageClass;
-  uint alignSize;
+  LinkageType linkageType; /// Current linkage type.
+  Protection protection; /// Current protection attribute.
+  StorageClass storageClass; /// Current storage classes.
+  uint alignSize; /// Current align size.
 
-  /// Construct a SemanticPass1 object.
+  /// Constructs a SemanticPass1 object.
   /// Params:
   ///   modul = the module to be processed.
+  ///   context = the compilation context.
   this(Module modul, CompilationContext context)
   {
     this.modul = modul;
@@ -53,7 +54,7 @@
     this.alignSize = context.structAlign;
   }
 
-  /// Start semantic analysis.
+  /// Starts processing the module.
   void start()
   {
     assert(modul.root !is null);
@@ -62,11 +63,13 @@
     visit(modul.root);
   }
 
+  /// Enters a new scope.
   void enterScope(ScopeSymbol s)
   {
     scop = scop.enter(s);
   }
 
+  /// Exits the current scope.
   void exitScope()
   {
     scop = scop.exit();
@@ -78,7 +81,7 @@
     return scop.symbol.isModule();
   }
 
-  /// Insert a symbol into the current scope.
+  /// Inserts a symbol into the current scope.
   void insert(Symbol symbol, Identifier* name)
   {
     auto symX = scop.symbol.lookup(name);
@@ -90,7 +93,7 @@
     symbol.parent = scop.symbol;
   }
 
-  /// Insert a symbol into scopeSym.
+  /// Inserts a symbol into scopeSym.
   void insert(Symbol symbol, ScopeSymbol scopeSym)
   {
     auto symX = scopeSym.lookup(symbol.name);
@@ -102,7 +105,7 @@
     symbol.parent = scopeSym;
   }
 
-  /// Insert a symbol, overloading on the name, into the current scope.
+  /// Inserts a symbol, overloading on the name, into the current scope.
   void insertOverload(Symbol sym, Identifier* name)
   {
     auto sym2 = scop.symbol.lookup(name);
@@ -120,7 +123,7 @@
     sym.parent = scop.symbol;
   }
 
-  /// Report error: new symbol s1 conflicts with existing symbol s2.
+  /// Reports an error: new symbol s1 conflicts with existing symbol s2.
   void reportSymbolConflict(Symbol s1, Symbol s2, Identifier* name)
   {
     auto loc = s2.node.begin.getErrorLocation();
@@ -128,6 +131,7 @@
     error(s1.node.begin, MSG.DeclConflictsWithDecl, name.str, locString);
   }
 
+  /// Creates an error report.
   void error(Token* token, char[] formatMsg, ...)
   {
     if (!modul.infoMan)
@@ -138,6 +142,7 @@
   }
 
 
+  /// Collects info about nodes which have to be evaluated later.
   static class Deferred
   {
     Node node;
@@ -149,11 +154,13 @@
     uint alignSize;
   }
 
-  // List of mixin, static if, static assert and pragma(msg,...) declarations.
-  // Their analysis must be deferred because they entail
-  // evaluation of expressions.
+  /// List of mixin, static if, static assert and pragma(msg,...) declarations.
+  ///
+  /// Their analysis must be deferred because they entail
+  /// evaluation of expressions.
   Deferred[] deferred;
 
+  /// Adds a deferred node to the list.
   void addDeferred(Node node)
   {
     auto d = new Deferred;
@@ -166,7 +173,7 @@
     deferred ~= d;
   }
 
-  private alias Declaration D;
+  private alias Declaration D; /// A handy alias. Saves typing.
 
 override
 {
--- a/trunk/src/dil/semantic/Pass2.d	Fri Feb 29 22:51:24 2008 +0100
+++ b/trunk/src/dil/semantic/Pass2.d	Sat Mar 01 02:53:06 2008 +0100
@@ -28,11 +28,16 @@
 import dil.CompilerInfo;
 import common;
 
+/// The second pass determines the types of symbols and the types
+/// of expressions and also evaluates them.
 class SemanticPass2 : DefaultVisitor
 {
   Scope scop; /// The current scope.
   Module modul; /// The module to be semantically checked.
 
+  /// Constructs a SemanticPass2 object.
+  /// Params:
+  ///   modul = the module to be checked.
   this(Module modul)
   {
     this.modul = modul;
@@ -47,21 +52,25 @@
     visit(modul.root);
   }
 
+  /// Enters a new scope.
   void enterScope(ScopeSymbol s)
   {
     scop = scop.enter(s);
   }
 
+  /// Exits the current scope.
   void exitScope()
   {
     scop = scop.exit();
   }
 
+  /// Evaluates e and returns the result.
   Expression interpret(Expression e)
   {
-    return Interpreter.interpret(e, modul.infoMan, scop);
+    return Interpreter.interpret(e, modul.infoMan/+, scop+/);
   }
 
+  /// Creates an error report.
   void error(Token* token, char[] formatMsg, ...)
   {
     auto location = token.getErrorLocation();
@@ -69,15 +78,16 @@
     modul.infoMan ~= new SemanticError(location, msg);
   }
 
+  /// Some handy aliases.
   private alias Declaration D;
-  private alias Expression E;
-  private alias Statement S;
-  private alias TypeNode T;
+  private alias Expression E; /// ditto
+  private alias Statement S; /// ditto
+  private alias TypeNode T; /// ditto
 
   /// The scope symbol to use in identifier or template instance expressions.
   /// E.g.: object.method(); // After 'object' has been visited, dotIdScope is
   ///                        // set, and 'method' will be looked up there.
-  ScopeSymbol dotIdScope;
+  //ScopeSymbol dotIdScope;
 
 override
 {
--- a/trunk/src/dil/semantic/Scope.d	Fri Feb 29 22:51:24 2008 +0100
+++ b/trunk/src/dil/semantic/Scope.d	Sat Mar 01 02:53:06 2008 +0100
@@ -9,6 +9,7 @@
 import dil.lexer.Identifier;
 import common;
 
+/// Builds a hierarchy of environments.
 class Scope
 {
   Scope parent; /// The surrounding scope, or null if this is the root scope.
@@ -21,27 +22,21 @@
     this.symbol = symbol;
   }
 
-  /++
-    Find a symbol in this scope.
-    Params:
-      name = the name of the symbol.
-  +/
+  /// Find a symbol in this scope.
+  /// Params:
+  ///   name = the name of the symbol.
   Symbol lookup(Identifier* name)
   {
     return symbol.lookup(name);
   }
 
-  /++
-    Create a new inner scope and return that.
-  +/
+  /// Create a new inner scope and return that.
   Scope enter(ScopeSymbol symbol)
   {
     return new Scope(this, symbol);
   }
 
-  /++
-    Destroy this scope and return the outer scope.
-  +/
+  /// Destroy this scope and return the outer scope.
   Scope exit()
   {
     auto sc = parent;
--- a/trunk/src/dil/semantic/Symbol.d	Fri Feb 29 22:51:24 2008 +0100
+++ b/trunk/src/dil/semantic/Symbol.d	Sat Mar 01 02:53:06 2008 +0100
@@ -8,7 +8,7 @@
 import dil.lexer.Identifier;
 import common;
 
-/// Symbol IDs.
+/// Enumeration of Symbol IDs.
 enum SYM
 {
   Module,
@@ -26,11 +26,9 @@
 //   Type,
 }
 
-/++
-  A symbol represents an object with semantic code information.
-+/
+/// A symbol represents an object with semantic code information.
 class Symbol
-{
+{ /// Enumeration of symbol statuses.
   enum Status : ushort
   {
     Declared,   /// The symbol has been declared.
@@ -46,6 +44,11 @@
   /// Useful for source code location info and retrieval of doc comments.
   Node node;
 
+  /// Constructs a Symbol object.
+  /// Params:
+  ///   sid = the symbol's ID.
+  ///   name = the symbol's name.
+  ///   node = the symbol's node.
   this(SYM sid, Identifier* name, Node node)
   {
     this.sid = sid;
@@ -53,19 +56,23 @@
     this.node = node;
   }
 
+  /// Change the status to Status.Completing.
   void setCompleting()
   { status = Status.Completing; }
 
+  /// Change the status to Status.Complete.
   void setComplete()
   { status = Status.Complete; }
 
+  /// Returns true if the symbol is being completed.
   bool isCompleting()
   { return status == Status.Completing; }
 
+  /// Returns true if the symbols is complete.
   bool isComplete()
   { return status == Status.Complete; }
 
-  // A template macro for building isXYZ() methods.
+  /// A template macro for building isXYZ() methods.
   private template isX(char[] kind)
   {
     const char[] isX = `bool is`~kind~`(){ return sid == SYM.`~kind~`; }`;
@@ -84,6 +91,7 @@
   mixin(isX!("OverloadSet"));
 //   mixin(isX!("Type"));
 
+  /// Casts the symbol to Class.
   Class to(Class)()
   {
     assert(mixin(`this.sid == mixin("SYM." ~ typeof(Class).stringof)`));
--- a/trunk/src/dil/semantic/SymbolTable.d	Fri Feb 29 22:51:24 2008 +0100
+++ b/trunk/src/dil/semantic/SymbolTable.d	Sat Mar 01 02:53:06 2008 +0100
@@ -8,14 +8,13 @@
 import dil.lexer.Identifier;
 import common;
 
-/++
-  Maps an identifier string to a Symbol.
-+/
+/// Maps an identifier string to a Symbol.
 struct SymbolTable
 {
-  Symbol[char[]] table;
+  Symbol[char[]] table; /// The table data structure.
 
-  /// Look up ident in the table.
+  /// Looks up ident in the table.
+  /// Returns: the symbol if there, otherwise null.
   Symbol lookup(Identifier* ident)
   {
     assert(ident !is null);
@@ -23,8 +22,9 @@
     return psym ? *psym : null;
   }
 
-  void insert(Symbol s, Identifier* ident)
+  /// Inserts a symbol into the table.
+  void insert(Symbol symbol, Identifier* ident)
   {
-    table[ident.str] = s;
+    table[ident.str] = symbol;
   }
 }
--- a/trunk/src/dil/semantic/Symbols.d	Fri Feb 29 22:51:24 2008 +0100
+++ b/trunk/src/dil/semantic/Symbols.d	Sat Mar 01 02:53:06 2008 +0100
@@ -68,6 +68,7 @@
   }
 }
 
+/// A class symbol.
 class Class : Aggregate
 {
   this(Identifier* name, Node classNode)
@@ -76,6 +77,7 @@
   }
 }
 
+/// An interface symbol.
 class Interface : Aggregate
 {
   this(Identifier* name, Node interfaceNode)
@@ -84,6 +86,7 @@
   }
 }
 
+/// A union symbol.
 class Union : Aggregate
 {
   this(Identifier* name, Node unionNode)
@@ -92,6 +95,7 @@
   }
 }
 
+/// A struct symbol.
 class Struct : Aggregate
 {
   this(Identifier* name, Node structNode)
@@ -100,6 +104,7 @@
   }
 }
 
+/// An enum symbol.
 class Enum : ScopeSymbol
 {
   TypeEnum type;
@@ -114,6 +119,7 @@
   }
 }
 
+/// A template symbol.
 class Template : ScopeSymbol
 {
   this(Identifier* name, Node templateNode)
@@ -122,6 +128,7 @@
   }
 }
 
+/// A function symbol.
 class Function : ScopeSymbol
 {
   Protection prot; /// The protection.
@@ -137,6 +144,7 @@
   }
 }
 
+/// A variable symbol.
 class Variable : Symbol
 {
   Protection prot; /// The protection.
@@ -158,6 +166,7 @@
   }
 }
 
+/// An enum member symbol.
 class EnumMember : Variable
 {
   this(Identifier* name,
@@ -169,6 +178,7 @@
   }
 }
 
+/// An alias symbol.
 class Alias : Symbol
 {
   this(Identifier* name, Node aliasNode)
@@ -177,10 +187,9 @@
   }
 }
 
-/++
-  A list of symbols that share the same identifier.
-  These can be functions, templates and aggregates with template parameter lists.
-+/
+/// A list of symbols that share the same identifier.
+///
+/// These can be functions, templates and aggregates with template parameter lists.
 class OverloadSet : Symbol
 {
   Symbol[] symbols;
--- a/trunk/src/dil/semantic/Types.d	Fri Feb 29 22:51:24 2008 +0100
+++ b/trunk/src/dil/semantic/Types.d	Sat Mar 01 02:53:06 2008 +0100
@@ -9,6 +9,7 @@
 import dil.lexer.Identifier;
 import dil.CompilerInfo;
 
+/// The base type for all type structures.
 abstract class Type/* : Symbol*/
 {
   Type next;     /// The next type in the type structure.
@@ -17,6 +18,10 @@
 
   this(){}
 
+  /// Constructs a Type object.
+  /// Params:
+  ///   next = the type's next type.
+  ///   tid = the type's ID.
   this(Type next, TYP tid)
   {
 //     this.sid = SYM.Type;
@@ -25,12 +30,13 @@
     this.tid = tid;
   }
 
+  /// Returns a pointer type to this type.
   TypePointer ptrTo()
   {
     return new TypePointer(this);
   }
 
-  /// Get byte size of this type.
+  /// Returns the byte size of this type.
   final size_t sizeOf()
   {
     return MITable.getSize(this);
@@ -42,12 +48,14 @@
     return sizeOf();
   }
 
+  /// Returns true if this type has a symbol.
   bool hasSymbol()
   {
     return symbol !is null;
   }
 }
 
+/// All basic types. E.g.: int, char, real etc.
 class TypeBasic : Type
 {
   this(TYP typ)
@@ -56,7 +64,7 @@
   }
 }
 
-/// Dynamic array.
+/// Dynamic array type.
 class TypeDArray : Type
 {
   this(Type next)
@@ -65,7 +73,7 @@
   }
 }
 
-/// Associative array.
+/// Associative array type.
 class TypeAArray : Type
 {
   Type keyType;
@@ -76,7 +84,7 @@
   }
 }
 
-/// Static array.
+/// Static array type.
 class TypeSArray : Type
 {
   size_t dimension;
@@ -87,6 +95,7 @@
   }
 }
 
+/// Pointer type.
 class TypePointer : Type
 {
   this(Type next)
@@ -95,6 +104,7 @@
   }
 }
 
+/// Reference type.
 class TypeReference : Type
 {
   this(Type next)
@@ -103,6 +113,7 @@
   }
 }
 
+/// Enum type.
 class TypeEnum : Type
 {
   this(Symbol symbol, Type baseType)
@@ -117,6 +128,7 @@
   }
 }
 
+/// Struct type.
 class TypeStruct : Type
 {
   this(Symbol symbol)
@@ -126,6 +138,7 @@
   }
 }
 
+/// Class type.
 class TypeClass : Type
 {
   this(Symbol symbol)
@@ -135,6 +148,7 @@
   }
 }
 
+/// Typedef type.
 class TypeTypedef : Type
 {
   this(Type next)
@@ -143,6 +157,7 @@
   }
 }
 
+/// Function type.
 class TypeFunction : Type
 {
   this(Type next)
@@ -151,6 +166,7 @@
   }
 }
 
+/// Delegate type.
 class TypeDelegate : Type
 {
   this(Type next)
@@ -159,6 +175,7 @@
   }
 }
 
+/// Identifier type.
 class TypeIdentifier : Type
 {
   Identifier* ident;
@@ -168,6 +185,7 @@
   }
 }
 
+/// Template instantiation type.
 class TypeTemplInstance : Type
 {
   this()
@@ -176,6 +194,7 @@
   }
 }
 
+/// Template tuple type.
 class TypeTuple : Type
 {
   this(Type next)
@@ -184,6 +203,7 @@
   }
 }
 
+/// Constant type. D2.0
 class TypeConst : Type
 {
   this(Type next)
@@ -192,6 +212,7 @@
   }
 }
 
+/// Invariant type. D2.0
 class TypeInvariant : Type
 {
   this(Type next)
@@ -200,7 +221,7 @@
   }
 }
 
-/// Represents a value related to a type.
+/// Represents a value related to a Type.
 union Value
 {
   void*  pvoid;
@@ -216,6 +237,7 @@
   creal  creal_;
 }
 
+/// Information related to a Type.
 struct TypeMetaInfo
 {
   char mangle; /// Mangle character of the type.
@@ -223,6 +245,7 @@
   Value* defaultInit; /// Default initialization value.
 }
 
+/// Namespace for the meta info table.
 struct MITable
 {
 static:
@@ -236,6 +259,7 @@
   const Value VCNAN = {creal_:creal.nan}; /// Value complex NAN.
   private alias SIZE_NOT_AVAILABLE SNA;
   private alias PTR_SIZE PS;
+  /// The meta info table.
   private const TypeMetaInfo metaInfoTable[] = [
     {'?', SNA}, // Error
 
@@ -286,6 +310,7 @@
   ];
   static assert(metaInfoTable.length == TYP.max+1);
 
+  /// Returns the size of a type.
   size_t getSize(Type type)
   {
     auto size = metaInfoTable[type.tid].size;
@@ -295,10 +320,11 @@
   }
 }
 
-/// A set of pre-defined types.
+/// Namespace for a set of predefined types.
 struct Types
 {
 static:
+  /// Predefined basic types.
   TypeBasic Char,   Wchar,   Dchar, Bool,
             Byte,   Ubyte,   Short, Ushort,
             Int,    Uint,    Long,  Ulong,
@@ -307,9 +333,11 @@
             Ifloat, Idouble, Ireal,
             Cfloat, Cdouble, Creal, Void;
 
-  TypeBasic Size_t, Ptrdiff_t;
-  TypePointer Void_ptr;
-  TypeBasic Error, Undefined;
+  TypeBasic Size_t; /// The size type.
+  TypeBasic Ptrdiff_t; /// The pointer difference type.
+  TypePointer Void_ptr; /// The void pointer type.
+  TypeBasic Error; /// The error type.
+  TypeBasic Undefined; /// The undefined type.
 
   /// Allocates an instance of TypeBasic and assigns it to typeName.
   template newTB(char[] typeName)
@@ -317,6 +345,7 @@
     const newTB = mixin(typeName~" = new TypeBasic(TYP."~typeName~")");
   }
 
+  /// Initializes predefined types.
   static this()
   {
     newTB!("Char");
--- a/trunk/src/dil/semantic/TypesEnum.d	Fri Feb 29 22:51:24 2008 +0100
+++ b/trunk/src/dil/semantic/TypesEnum.d	Sat Mar 01 02:53:06 2008 +0100
@@ -4,52 +4,53 @@
 +/
 module dil.semantic.TypesEnum;
 
+/// Enumeration of Type IDs.
 enum TYP
 {
   Error,
   // Basic types.
-  Char,    // char
-  Wchar,   // wchar
-  Dchar,   // dchar
-  Bool,    // bool
-  Byte,    // int8
-  Ubyte,   // uint8
-  Short,   // int16
-  Ushort,  // uint16
-  Int,     // int32
-  Uint,    // uint32
-  Long,    // int64
-  Ulong,   // uint64
-  Cent,    // int128
-  Ucent,   // uint128
-  Float,   // float32
-  Double,  // float64
-  Real,    // float80
-  Ifloat,  // imaginary float32
-  Idouble, // imaginary float64
-  Ireal,   // imaginary float80
-  Cfloat,  // complex float32
-  Cdouble, // complex float64
-  Creal,   // complex float80
-  Void,    // void
+  Char,    /// char
+  Wchar,   /// wchar
+  Dchar,   /// dchar
+  Bool,    /// bool
+  Byte,    /// int8
+  Ubyte,   /// uint8
+  Short,   /// int16
+  Ushort,  /// uint16
+  Int,     /// int32
+  Uint,    /// uint32
+  Long,    /// int64
+  Ulong,   /// uint64
+  Cent,    /// int128
+  Ucent,   /// uint128
+  Float,   /// float32
+  Double,  /// float64
+  Real,    /// float80
+  Ifloat,  /// imaginary float32
+  Idouble, /// imaginary float64
+  Ireal,   /// imaginary float80
+  Cfloat,  /// complex float32
+  Cdouble, /// complex float64
+  Creal,   /// complex float80
+  Void,    /// void
 
-  None,   // TypeNone in the specs. Why?
+  None,   /// TypeNone in the specs. Why?
 
-  DArray, // Dynamic
-  SArray, // Static
-  AArray, // Associative
+  DArray, /// Dynamic array.
+  SArray, /// Static array.
+  AArray, /// Associative array.
 
-  Enum,
-  Struct,
-  Class,
-  Typedef,
-  Function,
-  Delegate,
-  Pointer,
-  Reference,
-  Identifier,
-  TInstance, // Template instance.
-  Tuple,
-  Const, // D2
-  Invariant, // D2
+  Enum,       /// An enum.
+  Struct,     /// A struct.
+  Class,      /// A class.
+  Typedef,    /// A typedef.
+  Function,   /// A function.
+  Delegate,   /// A delegate.
+  Pointer,    /// A pointer.
+  Reference,  /// A reference.
+  Identifier, /// An identifier.
+  TInstance,  /// Template instance.
+  Tuple,      /// A template tuple.
+  Const,      /// A constant type. D2.0
+  Invariant,  /// An invariant type. D2.0
 }
--- a/trunk/src/dil/translator/German.d	Fri Feb 29 22:51:24 2008 +0100
+++ b/trunk/src/dil/translator/German.d	Sat Mar 01 02:53:06 2008 +0100
@@ -14,9 +14,7 @@
 
 private alias Declaration D;
 
-/++
-  Traverses a D syntax tree and explains in German.
-+/
+/// Translates a syntax tree into German.
 class GermanTranslator : DefaultVisitor
 {
   Print!(char) put; /// Output buffer.
@@ -30,12 +28,10 @@
   bool pluralize; /// Whether to use the plural when printing the next types.
   bool pointer; /// Whether next types should consider the previous pointer.
 
-  /++
-    Construct a GermanTranslator.
-    Params:
-      put = buffer to print to.
-      indentStep = added at every indendation step.
-  +/
+  /// Construct a GermanTranslator.
+  /// Params:
+  ///   put = buffer to print to.
+  ///   indentStep = added at every indendation step.
   this(Print!(char) put, char[] indentStep)
   {
     this.put = put;
@@ -48,6 +44,8 @@
     visitN(root);
   }
 
+  /// Increases the indentation when instantiated.
+  /// The indentation is restored when the instance goes out of scope.
   scope class Indent
   {
     char[] old_indent;
@@ -64,6 +62,8 @@
     { return this.outer.indent; }
   }
 
+  /// Saves an outer member when instantiated.
+  /// It is restored when the instance goes out of scope.
   scope class Enter(T)
   {
     T t_save;
@@ -100,6 +100,7 @@
   alias Enter!(FunctionDeclaration) EnteredFunction;
   alias Enter!(ConstructorDeclaration) EnteredConstructor;
 
+  /// Prints the location of a node: @(lin,col)
   void printLoc(Node node)
   {
     auto loc = node.begin.getRealLocation();
--- a/trunk/src/main.d	Fri Feb 29 22:51:24 2008 +0100
+++ b/trunk/src/main.d	Sat Mar 01 02:53:06 2008 +0100
@@ -41,6 +41,7 @@
 import tango.time.StopWatch;
 import tango.text.Ascii : icompare;
 
+/// Entry function of dil.
 void main(char[][] args)
 {
   auto infoMan = new InfoManager();
@@ -295,10 +296,10 @@
 
     Stdout.formatln("Scanned in {:f10}s.", swatch.stop);
     break;
-  case "parse":
-    if (args.length == 3)
-      parse(args[2]);
-    break;
+  // case "parse":
+  //   if (args.length == 3)
+  //     parse(args[2]);
+  //   break;
   case "?", "help":
     printHelp(args.length >= 3 ? args[2] : "");
     break;
@@ -319,6 +320,7 @@
   return text;
 }
 
+/// Available commands.
 const char[] COMMANDS =
   "  compile (c)\n"
   "  ddoc (d)\n"
@@ -382,6 +384,7 @@
   return true;
 }
 
+/// Prints the errors collected in infoMan.
 void printErrors(InfoManager infoMan)
 {
   foreach (info; infoMan.info)
@@ -402,6 +405,7 @@
   }
 }
 
+/// Prints the compiler's main help message.
 char[] helpMain()
 {
   auto COMPILED_WITH = __VENDOR__;
@@ -411,6 +415,7 @@
                    COMPILED_VERSION, COMPILED_DATE);
 }
 
+/// Prints a help message for command.
 void printHelp(char[] command)
 {
   char[] msg;
@@ -545,7 +550,7 @@
   Stdout(msg).newline;
 }
 
-void parse(string fileName)
+/+void parse(string fileName)
 {
   auto mod = new Module(fileName);
   mod.parse();
@@ -560,4 +565,4 @@
     }
   }
   print(mod.root.children, "");
-}
+}+/