Mercurial > projects > dil

changeset 783:8380fb2c765f

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Added documentation comments.
author Aziz K?ksal <aziz.koeksal@gmail.com>
date Sat, 23 Feb 2008 02:15:41 +0100
parents c4b28cf38760
children 939097e0990f
files trunk/src/cmd/ASTStats.d trunk/src/cmd/DDoc.d trunk/src/dil/lexer/Token.d trunk/src/dil/semantic/Pass1.d trunk/src/macros_dil.ddoc
diffstat 5 files changed, 66 insertions(+), 34 deletions(-) [+]
line wrap: on
line diff
--- a/trunk/src/cmd/ASTStats.d	Fri Feb 22 17:13:25 2008 +0100
+++ b/trunk/src/cmd/ASTStats.d	Sat Feb 23 02:15:41 2008 +0100
@@ -11,10 +11,12 @@
        dil.ast.Expression,
        dil.ast.Types;
 
+/// Counts the nodes in a syntax tree.
 class ASTStats : DefaultVisitor
 {
   uint[] table; /// Table for counting nodes.
 
+  /// Starts counting.
   uint[] count(Node root)
   {
     table = new uint[classNames.length];
--- a/trunk/src/cmd/DDoc.d	Fri Feb 22 17:13:25 2008 +0100
+++ b/trunk/src/cmd/DDoc.d	Sat Feb 23 02:15:41 2008 +0100
@@ -33,6 +33,7 @@
 import tango.io.File;
 import tango.io.FilePath;
 
+/// Executes the doc generation command.
 void execute(string[] filePaths, string destDir, string[] macroPaths,
              bool incUndoc, bool verbose, CompilationContext context,
              InfoManager infoMan)
@@ -89,15 +90,15 @@
   // Create a macro environment for this module.
   mtable = new MacroTable(mtable);
   // Define runtime macros.
+  // MODPATH is not in the specs.
   mtable.insert("MODPATH", mod.getFQNPath() ~ "." ~ mod.fileExtension());
-
   mtable.insert("TITLE", mod.getFQN());
   mtable.insert("DOCFILENAME", mod.getFQN() ~ ".html");
   auto timeStr = Time.toString();
   mtable.insert("DATETIME", timeStr);
   mtable.insert("YEAR", Time.year(timeStr));
 
-  auto doc = new DDocEmitter(mtable, incUndoc, mod, tokenHL);
+  auto doc = new DDocEmitter(mod, mtable, incUndoc, tokenHL);
   doc.emit();
   // Set BODY macro to the text produced by the DDocEmitter.
   mtable.insert("BODY", doc.text);
@@ -109,6 +110,7 @@
   file.write(fileText);
 }
 
+/// Loads a macro file. Converts any Unicode encoding to UTF-8.
 string loadMacroFile(string filePath, InfoManager infoMan)
 {
   auto src = new SourceText(filePath);
@@ -120,13 +122,19 @@
 /// Traverses the syntax tree and writes DDoc macros to a string buffer.
 class DDocEmitter : DefaultVisitor
 {
-  char[] text;
+  char[] text; /// The buffer that is written to.
   bool includeUndocumented;
   MacroTable mtable;
   Module modul;
   TokenHighlighter tokenHL;
 
-  this(MacroTable mtable, bool includeUndocumented, Module modul,
+  /// Constructs a DDocEmitter object.
+  /// Params:
+  ///   modul = the module to generate text for.
+  ///   mtable = the macro table.
+  ///   includeUndocumented = whether to include undocumented symbols.
+  ///   tokenHL = used to highlight code sections.
+  this(Module modul, MacroTable mtable, bool includeUndocumented,
        TokenHighlighter tokenHL)
   {
     this.mtable = mtable;
@@ -144,14 +152,10 @@
       {
         if (auto copyright = cmnt.takeCopyright())
           mtable.insert(new Macro("COPYRIGHT", copyright.text));
-        DESC({
-          writeComment();
-          MEMBERS("MODULE", { visitD(modul.root); });
-        });
+        writeComment();
       }
     }
-    else
-      MEMBERS("MODULE", { visitD(modul.root); });
+    MEMBERS("MODULE", { visitD(modul.root); });
     return text;
   }
 
@@ -163,13 +167,14 @@
     return Token.textSpan(left, right);
   }
 
-  TemplateParameters tparams; /// The template parameters of the declaration.
+  TemplateParameters tparams; /// The template parameters of the current declaration.
 
   DDocComment cmnt; /// Current comment.
   DDocComment prevCmnt; /// Previous comment in scope.
   /// An empty comment. Used for undocumented symbols.
   static const DDocComment emptyCmnt;
 
+  /// Initializes the empty comment.
   static this()
   {
     this.emptyCmnt = new DDocComment(null, null, null);
@@ -200,8 +205,9 @@
     }
   }
 
-  bool cmntIsDitto;
+  bool cmntIsDitto; /// True if current comment is "ditto".
 
+  /// Returns the DDocComment for node.
   DDocComment ddoc(Node node)
   {
     auto c = getDDocComment(node);
@@ -225,6 +231,7 @@
     return this.cmnt;
   }
 
+  /// List of predefined, special sections.
   static char[][char[]] specialSections;
   static this()
   {
@@ -234,6 +241,7 @@
       specialSections[name] = name;
   }
 
+  /// Writes the DDoc comment to the text buffer.
   void writeComment()
   {
     auto c = this.cmnt;
@@ -274,6 +282,14 @@
     write(")");
   }
 
+  /// Scans the comment text and:
+  /// $(UL
+  /// $(LI skips and leaves macro invocations unchanged)
+  /// $(LI skips HTML tags)
+  /// $(LI escapes '(', ')', '<', '>' and '&')
+  /// $(LI inserts $&#40;DDOC_BLANKLINE&#41; in place of \n\n)
+  /// $(LI highlights code in code sections)
+  /// )
   char[] scanCommentText(char[] text)
   {
     char* p = text.ptr;
@@ -385,6 +401,14 @@
     return text;
   }
 
+  /// Writes an array of strings to the text buffer.
+  void write(char[][] strings...)
+  {
+    foreach (s; strings)
+      text ~= s;
+  }
+
+  /// Writes params to the text buffer.
   void writeParams(Parameters params)
   {
     if (!params.items.length)
@@ -416,6 +440,7 @@
     write(")");
   }
 
+  /// Writes the current template parameters to the text buffer.
   void writeTemplateParams()
   {
     if (!tparams)
@@ -424,6 +449,7 @@
     tparams = null;
   }
 
+  /// Writes bases to the text buffer.
   void writeInheritanceList(BaseClassType[] bases)
   {
     if (bases.length == 0)
@@ -434,12 +460,7 @@
     write(" : ", escape(textSpan(basesBegin, bases[$-1].end)));
   }
 
-  void write(char[][] strings...)
-  {
-    foreach (s; strings)
-      text ~= s;
-  }
-
+  /// Writes a symbol to the text buffer. E.g: $&#40;SYMBOL Buffer, 123&#41;
   void SYMBOL(char[] name, Declaration d)
   {
     auto loc = d.begin.getRealLocation();
@@ -448,8 +469,10 @@
     // write("$(DDOC_PSYMBOL ", name, ")");
   }
 
+  /// Offset at which to insert a declaration which have a "ditto" comment.
   uint prevDeclOffset;
 
+  /// Writes a declaration to the text buffer.
   void DECL(void delegate() dg, Declaration d, bool writeSemicolon = true)
   {
     if (cmntIsDitto)
@@ -476,6 +499,7 @@
     prevDeclOffset = text.length;
   }
 
+  /// Wraps the DDOC_DECL_DD macro around the text written by dg().
   void DESC(void delegate() dg)
   {
     if (cmntIsDitto)
@@ -485,6 +509,7 @@
     write(")");
   }
 
+  /// Wraps the DDOC_kind_MEMBERS macro around the text written by dg().
   void MEMBERS(char[] kind, void delegate() dg)
   {
     write("\n$(DDOC_"~kind~"_MEMBERS ");
@@ -492,6 +517,7 @@
     write(")");
   }
 
+  /// Writes a class or interface declaration.
   void writeClassOrInterface(T)(T d)
   {
     if (!ddoc(d))
@@ -511,6 +537,7 @@
     });
   }
 
+  /// Writes a struct or union declaration.
   void writeStructOrUnion(T)(T d)
   {
     if (!ddoc(d))
@@ -530,6 +557,7 @@
     });
   }
 
+  /// Writes an alias or typedef declaration.
   void writeAliasOrTypedef(T)(T d)
   {
     auto prefix = is(T == AliasDeclaration) ? "alias " : "typedef ";
@@ -545,6 +573,7 @@
     DESC({ writeComment(); });
   }
 
+  /// Writes the attributes of a declaration in brackets.
   void writeAttributes(Declaration d)
   {
     char[][] attributes;
--- a/trunk/src/dil/lexer/Token.d	Fri Feb 22 17:13:25 2008 +0100
+++ b/trunk/src/dil/lexer/Token.d	Sat Feb 23 02:15:41 2008 +0100
@@ -13,11 +13,9 @@
 
 public import dil.lexer.TokensEnum;
 
-/++
-  A Token is a sequence of characters formed by the lexical analyzer.
-+/
+/// A Token is a sequence of characters formed by the lexical analyzer.
 struct Token
-{
+{ /// Flags set by the Lexer.
   enum Flags : ushort
   {
     None,
@@ -29,11 +27,14 @@
   /// Pointers to the next and previous tokens (doubly-linked list.)
   Token* next, prev;
 
-  char* ws;    /// Start of whitespace characters before token. Null if no WS.
+  /// 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.
 
-  // Data associated with this token.
+  /// Data associated with this token.
+  /// TODO: move data structures out; use only pointers here to keep Token.sizeof small.
   union
   {
     /// For newline tokens.
@@ -47,7 +48,7 @@
     /// For string tokens.
     struct
     {
-      string str;
+      string str; /// Zero-terminated string.
       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
@@ -55,7 +56,7 @@
                           EOF in case end of source text is "q{" EOF.
                       +/
     }
-    Identifier* ident;
+    Identifier* ident; /// For keywords and identifiers.
     dchar  dchar_;
     long   long_;
     ulong  ulong_;
@@ -66,8 +67,6 @@
     real   real_;
   }
 
-  alias srcText identifier;
-
   /// Returns the text of the token.
   string srcText()
   {
@@ -114,6 +113,7 @@
     return token;
   }
 
+  /// Returns the string for token kind tok.
   static string toString(TOK tok)
   {
     return tokToString[tok];
@@ -125,11 +125,9 @@
     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.
-  +/
+  /// 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()
   {
     return kind == TOK.String && start[0] != '\\' ||
@@ -267,6 +265,7 @@
     return left.start[0 .. right.end - left.start];
   }
 
+  /// Uses malloc() to allocate memory for a token.
   new(size_t size)
   {
     void* p = malloc(size);
@@ -276,6 +275,7 @@
     return p;
   }
 
+  /// Deletes a token using free().
   delete(void* p)
   {
     auto token = cast(Token*)p;
--- a/trunk/src/dil/semantic/Pass1.d	Fri Feb 22 17:13:25 2008 +0100
+++ b/trunk/src/dil/semantic/Pass1.d	Sat Feb 23 02:15:41 2008 +0100
@@ -320,7 +320,7 @@
   D visit(VariablesDeclaration vd)
   {
     // Error if we are in an interface.
-    if (scop.symbol.isInterface)
+    if (scop.symbol.isInterface && !vd.isStatic)
       return error(vd.begin, MSG.InterfaceCantHaveVariables), vd;
 
     // Insert variable symbols in this declaration into the symbol table.
--- a/trunk/src/macros_dil.ddoc	Fri Feb 22 17:13:25 2008 +0100
+++ b/trunk/src/macros_dil.ddoc	Sat Feb 23 02:15:41 2008 +0100
@@ -16,3 +16,4 @@
 COPYRIGHT = Copyright © 2007-$(YEAR), Aziz Köksal. All rights reserved.
 SYMBOL_ = <a href="http://hg.sharesource.org/dil/file/tip/trunk/src/$(MODPATH)#L$2">$1</a>
 SYMBOL = <a href="$(SRCFILE)#L$2">$1</a>
+