--- a/dmd/ddoc/DocComment.d	Wed Sep 15 02:47:24 2010 +0200
+++ b/dmd/ddoc/DocComment.d	Wed Sep 15 03:00:30 2010 +0200
@@ -1,9 +1,9 @@
 module dmd.ddoc.DocComment;
 
+import dmd.ddoc.Escape;
+import dmd.ddoc.Macro;
 import dmd.ddoc.Sections;
 import dmd.Array;
-import dmd.Macro;
-import dmd.Escape;
 import dmd.Scope;
 import dmd.Dsymbol;
 import dmd.OutBuffer;
@@ -28,7 +28,7 @@
 	{
 		unsigned idlen;
 
-		//printf("parse(%s): '%s'\n", s.toChars(), comment);
+		// writef("parse(%s): '%s'\n", s.toChars(), comment);
 		if (sc.lastdc && isDitto(comment))
 		return null;
 
@@ -54,11 +54,25 @@
 		return dc;
 	}
 	
+	/************************************************
+	 * Parse macros out of Macros: section.
+	 * Macros are of the form:
+	 *	  name1 = value1
+	 *
+	 *	  name2 = value2
+	 */
 	static void parseMacros(Escape** pescapetable, Macro** pmacrotable, ubyte* m, uint mlen)
 	{
 		assert(false);
 	}
 	
+	/**************************************
+	 * Parse escapes of the form:
+	 *	  /c/string/
+	 * where c is a single character.
+	 * Multiple escapes can be separated
+	 * by whitespace and/or commas.
+	 */
 	static void parseEscapes(Escape** pescapetable, ubyte* textstart, uint textlen)
 	{
 		assert(false);
@@ -70,7 +84,7 @@
 	 * If paragraph ends in 'identifier:',
 	 * then (*pcomment)[0 .. idlen] is the identifier.
 	 */
-	void parseSections(ubyte* comment)
+	void parseSections(string comment)
 	{
 		ubyte*p;
 		ubyte*pstart;