# HG changeset patch # User Aziz K?ksal # Date 1203729341 -3600 # Node ID 8380fb2c765f4a018b5d18be6b56db54cdc97450 # Parent c4b28cf38760431e2cb1bf1a234c973602c8ca76 Added documentation comments. diff -r c4b28cf38760 -r 8380fb2c765f trunk/src/cmd/ASTStats.d --- 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]; diff -r c4b28cf38760 -r 8380fb2c765f trunk/src/cmd/DDoc.d --- 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 $(DDOC_BLANKLINE) 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: $(SYMBOL Buffer, 123) 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; diff -r c4b28cf38760 -r 8380fb2c765f trunk/src/dil/lexer/Token.d --- 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; diff -r c4b28cf38760 -r 8380fb2c765f trunk/src/dil/semantic/Pass1.d --- 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. diff -r c4b28cf38760 -r 8380fb2c765f trunk/src/macros_dil.ddoc --- 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_ = $1 SYMBOL = $1 +