Comment handling improvements

Fixes bug 529040, bug 540513, and bug 546096.

37 files changed, 332 insertions, 275 deletions

diff --git a/ccode/valaccodewriter.vala b/ccode/valaccodewriter.vala
index 26326fbd9..11559cd54 100644
--- a/ccode/valaccodewriter.vala
+++ b/ccode/valaccodewriter.vala
@@ -142,7 +142,7 @@ public class Vala.CCodeWriter {
 	 * @param s a string
 	 */
 	public void write_string (string s) {
-		stream.printf ("%s", s);
+		stream.puts (s);
 		_bol = false;
 	}
 	
@@ -177,7 +177,7 @@ public class Vala.CCodeWriter {
 		
 		indent--;
 		write_indent ();
-		stream.printf ("}");
+		stream.putc ('}');
 	}
 	
 	/**
@@ -187,7 +187,7 @@ public class Vala.CCodeWriter {
 	 */
 	public void write_comment (string text) {
 		write_indent ();
-		stream.printf ("/*");
+		stream.puts ("/*");
 		bool first = true;
 		
 		/* separate declaration due to missing memory management in foreach statements */
@@ -199,9 +199,17 @@ public class Vala.CCodeWriter {
 			} else {
 				first = false;
 			}
-			stream.printf ("%s", line);
+
+			var lineparts = line.split ("*/");
+
+			for (int i = 0; lineparts[i] != null; i++) {
+				stream.puts (lineparts[i]);
+				if (lineparts[i+1] != null) {
+					stream.puts ("* /");
+				}
+			}
 		}
-		stream.printf ("*/");
+		stream.puts ("*/");
 		write_newline ();
 	}
 }
diff --git a/codegen/valaccodebasemodule.vala b/codegen/valaccodebasemodule.vala
index ed3ef180f..a5f628b99 100644
--- a/codegen/valaccodebasemodule.vala
+++ b/codegen/valaccodebasemodule.vala
@@ -609,11 +609,6 @@ internal class Vala.CCodeBaseModule : CCodeModule {
 
 			source_type_member_definition.append (cfunc);
 		}
-
-		CCodeComment comment = null;
-		if (source_file.comment != null) {
-			comment = new CCodeComment (source_file.comment);
-		}
 		
 		var writer = new CCodeWriter (source_file.get_csource_filename ());
 		if (!writer.open ()) {
@@ -621,9 +616,15 @@ internal class Vala.CCodeBaseModule : CCodeModule {
 			return;
 		}
 		writer.line_directives = context.debug;
-		if (comment != null) {
-			comment.write (writer);
+
+		var comments = source_file.get_comments();
+		if (comments != null) {
+			foreach (Comment comment in comments) {
+				var ccomment = new CCodeComment (comment.content);
+				ccomment.write (writer);
+			}
 		}
+
 		writer.write_newline ();
 		source_declarations.include_directives.write (writer);
 		writer.write_newline ();
@@ -687,10 +688,6 @@ internal class Vala.CCodeBaseModule : CCodeModule {
 				cenum.add_value (new CCodeEnumValue (ev.get_cname (), (CCodeExpression) ev.value.ccodenode));
 			}
 		}
-		
-		if (en.source_reference.comment != null) {
-			decl_space.add_type_definition (new CCodeComment (en.source_reference.comment));
-		}
 
 		decl_space.add_type_definition (cenum);
 		decl_space.add_type_definition (new CCodeNewline ());
@@ -1568,11 +1565,6 @@ internal class Vala.CCodeBaseModule : CCodeModule {
 			if (stmt.error) {
 				continue;
 			}
-
-			var src = stmt.source_reference;
-			if (src != null && src.comment != null) {
-				cblock.add_statement (new CCodeComment (src.comment));
-			}
 			
 			if (stmt.ccodenode is CCodeFragment) {
 				foreach (CCodeNode cstmt in ((CCodeFragment) stmt.ccodenode).get_children ()) {
diff --git a/codegen/valaccodedelegatemodule.vala b/codegen/valaccodedelegatemodule.vala
index 229304790..678ffe781 100644
--- a/codegen/valaccodedelegatemodule.vala
+++ b/codegen/valaccodedelegatemodule.vala
@@ -103,10 +103,6 @@ internal class Vala.CCodeDelegateModule : CCodeArrayModule {
 		}
 
 		var ctypedef = new CCodeTypeDefinition (return_type_cname, cfundecl);
-
-		if (d.source_reference != null && d.source_reference.comment != null) {
-			decl_space.add_type_definition (new CCodeComment (d.source_reference.comment));
-		}
 		decl_space.add_type_definition (ctypedef);
 	}
 
diff --git a/codegen/valaccodemethodmodule.vala b/codegen/valaccodemethodmodule.vala
index ce19438d3..72412c89a 100644
--- a/codegen/valaccodemethodmodule.vala
+++ b/codegen/valaccodemethodmodule.vala
@@ -455,9 +455,6 @@ internal class Vala.CCodeMethodModule : CCodeStructModule {
 				}
 
 				if (!m.coroutine) {
-					if (m.source_reference != null && m.source_reference.comment != null) {
-						source_type_member_definition.append (new CCodeComment (m.source_reference.comment));
-					}
 					source_type_member_definition.append (function);
 				}
 			
@@ -900,9 +897,6 @@ internal class Vala.CCodeMethodModule : CCodeStructModule {
 
 		vfunc.block = vblock;
 
-		if (m.is_abstract && m.source_reference != null && m.source_reference.comment != null) {
-			source_type_member_definition.append (new CCodeComment (m.source_reference.comment));
-		}
 		source_type_member_definition.append (vfunc);
 	}
 
diff --git a/codegen/valaccodestructmodule.vala b/codegen/valaccodestructmodule.vala
index f61759842..d8f5d4db7 100644
--- a/codegen/valaccodestructmodule.vala
+++ b/codegen/valaccodestructmodule.vala
@@ -101,9 +101,6 @@ internal class Vala.CCodeStructModule : CCodeBaseModule {
 
 		decl_space.add_type_declaration (new CCodeTypeDefinition ("struct _%s".printf (st.get_cname ()), new CCodeVariableDeclarator (st.get_cname ())));
 
-		if (st.source_reference.comment != null) {
-			decl_space.add_type_definition (new CCodeComment (st.source_reference.comment));
-		}
 		decl_space.add_type_definition (instance_struct);
 
 		var function = new CCodeFunction (st.get_dup_function (), st.get_cname () + "*");
diff --git a/codegen/valagerrormodule.vala b/codegen/valagerrormodule.vala
index cadaf8c01..2ab64a0b6 100644
--- a/codegen/valagerrormodule.vala
+++ b/codegen/valagerrormodule.vala
@@ -49,9 +49,6 @@ internal class Vala.GErrorModule : CCodeDelegateModule {
 			}
 		}
 
-		if (edomain.source_reference.comment != null) {
-			decl_space.add_type_definition (new CCodeComment (edomain.source_reference.comment));
-		}
 		decl_space.add_type_definition (cenum);
 
 		string quark_fun_name = edomain.get_lower_case_cprefix () + "quark";
diff --git a/codegen/valagobjectmodule.vala b/codegen/valagobjectmodule.vala
index e148b31fb..aaab3f87a 100644
--- a/codegen/valagobjectmodule.vala
+++ b/codegen/valagobjectmodule.vala
@@ -483,9 +483,6 @@ internal class Vala.GObjectModule : GTypeModule {
 		
 			function.block = cblock;
 
-			if (c.source_reference.comment != null) {
-				source_type_member_definition.append (new CCodeComment (c.source_reference.comment));
-			}
 			source_type_member_definition.append (function);
 		} else if (c.binding == MemberBinding.CLASS) {
 			// class constructor
diff --git a/codegen/valagtypemodule.vala b/codegen/valagtypemodule.vala
index 8e7a245d8..6b7f3ec58 100644
--- a/codegen/valagtypemodule.vala
+++ b/codegen/valagtypemodule.vala
@@ -309,9 +309,6 @@ internal class Vala.GTypeModule : GErrorModule {
 			}
 		}
 
-		if (cl.source_reference.comment != null) {
-			decl_space.add_type_definition (new CCodeComment (cl.source_reference.comment));
-		}
 		if (!cl.is_compact || cl.base_class == null) {
 			// derived compact classes do not have a struct
 			decl_space.add_type_definition (instance_struct);
@@ -1773,9 +1770,6 @@ internal class Vala.GTypeModule : GErrorModule {
 			}
 		}
 
-		if (iface.source_reference.comment != null) {
-			decl_space.add_type_definition (new CCodeComment (iface.source_reference.comment));
-		}
 		decl_space.add_type_definition (type_struct);
 
 		var type_fun = create_interface_register_function (iface);
diff --git a/vala/Makefile.am b/vala/Makefile.am
index 31b2845d2..e5bdde695 100644
--- a/vala/Makefile.am
+++ b/vala/Makefile.am
@@ -40,6 +40,7 @@ libvalacore_la_VALASOURCES = \
 	valacodenode.vala \
 	valacodevisitor.vala \
 	valacodewriter.vala \
+	valacomment.vala \
 	valaconditionalexpression.vala \
 	valaconstant.vala \
 	valaconstructor.vala \
diff --git a/vala/valaclass.vala b/vala/valaclass.vala
index e4b193f05..f88efabaa 100644
--- a/vala/valaclass.vala
+++ b/vala/valaclass.vala
@@ -241,10 +241,11 @@ public class Vala.Class : ObjectTypeSymbol {
 	 *
 	 * @param name   type name
 	 * @param source reference to source code
+	 * @param comment class documentation
 	 * @return       newly created class
 	 */
-	public Class (string name, SourceReference? source_reference = null) {
-		base (name, source_reference);
+	public Class (string name, SourceReference? source_reference = null, Comment? comment = null) {
+		base (name, source_reference, comment);
 	}
 
 	/**
diff --git a/vala/valacomment.vala b/vala/valacomment.vala
new file mode 100644
index 000000000..0e48f897e
--- /dev/null
+++ b/vala/valacomment.vala
@@ -0,0 +1,45 @@
+/* valacomment.vala
+ *
+ * Copyright (C) 2008-2009  Florian Brosch
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 2.1 of the License, or (at your option) any later version.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this library; if not, write to the Free Software
+ * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301  USA
+ *
+ * Author:
+ * 	Florian Brosch <flo.brosch@gmail.com>
+ */
+
+using GLib;
+
+/**
+ * A documentation comment used by valadoc
+ */
+public class Vala.Comment {
+	public Comment (string comment, SourceReference _source_reference) {
+		source_reference = _source_reference;
+		content = comment;
+	}
+
+	/**
+	 * The text describing the referenced source code.
+	 */
+	public string content { set; get; }
+
+	/**
+	 * References the location in the source file where this code node has
+	 * been written.
+	 */
+	public SourceReference source_reference { get; set; }
+}
+
diff --git a/vala/valaconstant.vala b/vala/valaconstant.vala
index 54722c37a..b382bcb59 100644
--- a/vala/valaconstant.vala
+++ b/vala/valaconstant.vala
@@ -67,8 +67,8 @@ public class Vala.Constant : Member, Lockable {
 	 * @param source_reference reference to source code
 	 * @return                 newly created constant
 	 */
-	public Constant (string name, DataType type_reference, Expression? initializer, SourceReference? source_reference) {
-		base (name, source_reference);
+	public Constant (string name, DataType type_reference, Expression? initializer, SourceReference? source_reference, Comment? comment = null) {
+		base (name, source_reference, comment);
 		this.type_reference = type_reference;
 		this.initializer = initializer;
 	}
diff --git a/vala/valacreationmethod.vala b/vala/valacreationmethod.vala
index 3051e52eb..79cfa8eb0 100644
--- a/vala/valacreationmethod.vala
+++ b/vala/valacreationmethod.vala
@@ -59,8 +59,8 @@ public class Vala.CreationMethod : Method {
 	 * @param source_reference reference to source code
 	 * @return                 newly created method
 	 */
-	public CreationMethod (string? class_name, string? name, SourceReference? source_reference = null) {
-		base (name, new VoidType (), source_reference);
+	public CreationMethod (string? class_name, string? name, SourceReference? source_reference = null, Comment? comment = null) {
+		base (name, new VoidType (), source_reference, comment);
 		this.class_name = class_name;
 
 		carray_length_parameter_position = -3;
diff --git a/vala/valadelegate.vala b/vala/valadelegate.vala
index 033058db7..8af715773 100644
--- a/vala/valadelegate.vala
+++ b/vala/valadelegate.vala
@@ -90,8 +90,8 @@ public class Vala.Delegate : TypeSymbol {
 	 * @param source      reference to source code
 	 * @return            newly created delegate
 	 */
-	public Delegate (string? name, DataType return_type, SourceReference? source_reference = null) {
-		base (name, source_reference);
+	public Delegate (string? name, DataType return_type, SourceReference? source_reference = null, Comment? comment = null) {
+		base (name, source_reference, comment);
 		this.return_type = return_type;
 
 		// error is -1 (right of user_data)
diff --git a/vala/valadynamicmethod.vala b/vala/valadynamicmethod.vala
index 96f0cfa5c..06c58fbba 100644
--- a/vala/valadynamicmethod.vala
+++ b/vala/valadynamicmethod.vala
@@ -34,8 +34,8 @@ public class Vala.DynamicMethod : Method {
 	private string cname;
 	static int dynamic_method_id;
 
-	public DynamicMethod (DataType dynamic_type, string name, DataType return_type, SourceReference? source_reference = null) {
-		base (name, return_type, source_reference);
+	public DynamicMethod (DataType dynamic_type, string name, DataType return_type, SourceReference? source_reference = null, Comment? comment = null) {
+		base (name, return_type, source_reference, comment);
 		this.dynamic_type = dynamic_type;
 	}
 
diff --git a/vala/valadynamicproperty.vala b/vala/valadynamicproperty.vala
index c7ee1253a..3139f5f5f 100644
--- a/vala/valadynamicproperty.vala
+++ b/vala/valadynamicproperty.vala
@@ -29,8 +29,8 @@ using Gee;
 public class Vala.DynamicProperty : Property {
 	public DataType dynamic_type { get; set; }
 
-	public DynamicProperty (DataType dynamic_type, string name, SourceReference? source_reference = null) {
-		base (name, null, null, null, source_reference);
+	public DynamicProperty (DataType dynamic_type, string name, SourceReference? source_reference = null, Comment? comment = null) {
+		base (name, null, null, null, source_reference, comment);
 		this.dynamic_type = dynamic_type;
 	}
 
diff --git a/vala/valadynamicsignal.vala b/vala/valadynamicsignal.vala
index 695c302e9..dc1757eb4 100644
--- a/vala/valadynamicsignal.vala
+++ b/vala/valadynamicsignal.vala
@@ -30,8 +30,8 @@ public class Vala.DynamicSignal : Signal {
 
 	public Expression handler { get; set; }
 
-	public DynamicSignal (DataType dynamic_type, string name, DataType return_type, SourceReference? source_reference = null) {
-		base (name, return_type, source_reference);
+	public DynamicSignal (DataType dynamic_type, string name, DataType return_type, SourceReference? source_reference = null, Comment? comment = null) {
+		base (name, return_type, source_reference, comment);
 		this.dynamic_type = dynamic_type;
 	}
 
diff --git a/vala/valaenum.vala b/vala/valaenum.vala
index 1d1e8c112..b348f9c91 100644
--- a/vala/valaenum.vala
+++ b/vala/valaenum.vala
@@ -52,8 +52,8 @@ public class Vala.Enum : TypeSymbol {
 	 * @param source_reference reference to source code
 	 * @return                 newly created enum
 	 */
-	public Enum (string name, SourceReference? source_reference = null) {
-		base (name, source_reference);
+	public Enum (string name, SourceReference? source_reference = null, Comment? comment = null) {
+		base (name, source_reference, comment);
 	}
 	
 	/**
diff --git a/vala/valaenumvalue.vala b/vala/valaenumvalue.vala
index 8fbcc5729..eaade92c1 100644
--- a/vala/valaenumvalue.vala
+++ b/vala/valaenumvalue.vala
@@ -31,6 +31,8 @@ public class Vala.EnumValue : Symbol {
 	 */
 	public Expression value { get; set; }
 
+	public Comment comment { get; set; }
+
 	private string cname;
 
 	/**
@@ -39,8 +41,9 @@ public class Vala.EnumValue : Symbol {
 	 * @param name enum value name
 	 * @return     newly created enum value
 	 */
-	public EnumValue (string name, SourceReference? source_reference = null) {
+	public EnumValue (string name, SourceReference? source_reference = null, Comment? comment = null) {
 		base (name, source_reference);
+		this.comment = comment;
 	}
 
 	/**
@@ -50,8 +53,8 @@ public class Vala.EnumValue : Symbol {
 	 * @param value numerical representation
 	 * @return      newly created enum value
 	 */
-	public EnumValue.with_value (string name, Expression value, SourceReference? source_reference = null) {
-		this (name, source_reference);
+	public EnumValue.with_value (string name, Expression value, SourceReference? source_reference = null, Comment? comment = null) {
+		this (name, source_reference, comment);
 		this.value = value;
 	}
 	
diff --git a/vala/valaerrorcode.vala b/vala/valaerrorcode.vala
index 83ba9a687..24d7f60ec 100644
--- a/vala/valaerrorcode.vala
+++ b/vala/valaerrorcode.vala
@@ -39,8 +39,8 @@ public class Vala.ErrorCode : TypeSymbol {
 	 * @param name enum value name
 	 * @return     newly created enum value
 	 */
-	public ErrorCode (string name, SourceReference? source_reference = null) {
-		base (name, source_reference);
+	public ErrorCode (string name, SourceReference? source_reference = null, Comment? comment = null) {
+		base (name, source_reference, comment);
 	}
 
 	/**
diff --git a/vala/valaerrordomain.vala b/vala/valaerrordomain.vala
index eecd97c8e..6802fa88a 100644
--- a/vala/valaerrordomain.vala
+++ b/vala/valaerrordomain.vala
@@ -41,8 +41,8 @@ public class Vala.ErrorDomain : TypeSymbol {
 	 * @param source_reference reference to source code
 	 * @return                 newly created error domain
 	 */
-	public ErrorDomain (string name, SourceReference? source_reference = null) {
-		base (name, source_reference);
+	public ErrorDomain (string name, SourceReference? source_reference = null, Comment? comment = null) {
+		base (name, source_reference, comment);
 	}
 	
 	/**
diff --git a/vala/valafield.vala b/vala/valafield.vala
index 43336a89f..3573354c3 100644
--- a/vala/valafield.vala
+++ b/vala/valafield.vala
@@ -115,8 +115,8 @@ public class Vala.Field : Member, Lockable {
 	 * @param source reference to source code
 	 * @return       newly created field
 	 */
-	public Field (string name, DataType field_type, Expression? initializer, SourceReference? source_reference = null) {
-		base (name, source_reference);
+	public Field (string name, DataType field_type, Expression? initializer, SourceReference? source_reference = null, Comment? comment = null) {
+		base (name, source_reference, comment);
 		this.field_type = field_type;
 		this.initializer = initializer;
 	}
diff --git a/vala/valagenieparser.vala b/vala/valagenieparser.vala
index 8c965e7f7..f61f65a31 100644
--- a/vala/valagenieparser.vala
+++ b/vala/valagenieparser.vala
@@ -40,7 +40,7 @@ public class Vala.Genie.Parser : CodeVisitor {
 	// number of tokens in buffer
 	int size;
 
-	string comment;
+	Comment comment;
 	
 	string class_name;
 	
@@ -194,14 +194,6 @@ public class Vala.Genie.Parser : CodeVisitor {
 		return new SourceReference (scanner.source_file, begin.line, begin.column, tokens[last_index].end.line, tokens[last_index].end.column);
 	}
 
-	SourceReference get_src_com (SourceLocation begin) {
-		int last_index = (index + BUFFER_SIZE - 1) % BUFFER_SIZE;
-
-		var src = new SourceReference.with_comment (scanner.source_file, begin.line, begin.column, tokens[last_index].end.line, tokens[last_index].end.column, comment);
-		comment = null;
-		return src;
-	}
-
 	SourceReference get_current_src () {
 		return new SourceReference (scanner.source_file, tokens[index].begin.line, tokens[index].begin.column, tokens[index].end.line, tokens[index].end.column);
 	}
@@ -1564,7 +1556,7 @@ public class Vala.Genie.Parser : CodeVisitor {
 						expect (TokenType.EOL);
 					}
 		
-					stmt =  new EmptyStatement (get_src_com (begin));
+					stmt =  new EmptyStatement (get_src (begin));
 					break;				
 
 
@@ -1700,7 +1692,7 @@ public class Vala.Genie.Parser : CodeVisitor {
 
 		comment = scanner.pop_comment ();
 
-		var block = new Block (get_src_com (get_location ()));
+		var block = new Block (get_src (get_location ()));
 		block.add_statement (parse_embedded_statement_without_block ());
 		return block;
 
@@ -1730,7 +1722,7 @@ public class Vala.Genie.Parser : CodeVisitor {
 	Block parse_block () throws ParseError {
 		var begin = get_location ();
 		expect (TokenType.INDENT);
-		var block = new Block (get_src_com (begin));
+		var block = new Block (get_src (begin));
 		parse_statements (block);
 		if (!accept (TokenType.DEDENT)) {
 			// only report error if it's not a secondary error
@@ -1752,7 +1744,7 @@ public class Vala.Genie.Parser : CodeVisitor {
 		accept (TokenType.SEMICOLON);
 		expect_terminator ();
 
-		return new EmptyStatement (get_src_com (begin));
+		return new EmptyStatement (get_src (begin));
 	}
 
 	void add_local_var_variable (Block block, string id)  throws ParseError {
@@ -1811,7 +1803,7 @@ public class Vala.Genie.Parser : CodeVisitor {
 		if (accept (TokenType.ASSIGN)) {
 			initializer = parse_expression ();
 		}
-		return new LocalVariable (variable_type, id, initializer, get_src_com (begin));
+		return new LocalVariable (variable_type, id, initializer, get_src (begin));
 	}
 
 	Statement parse_expression_statement () throws ParseError {
@@ -1824,7 +1816,7 @@ public class Vala.Genie.Parser : CodeVisitor {
 			expect_terminator ();
 		}
 
-		return new ExpressionStatement (expr, get_src_com (begin));
+		return new ExpressionStatement (expr, get_src (begin));
 	}
 
 	Expression parse_statement_expression () throws ParseError {
@@ -1847,7 +1839,7 @@ public class Vala.Genie.Parser : CodeVisitor {
 			accept (TokenType.EOL);
 		}
 
-		var src = get_src_com (begin);
+		var src = get_src (begin);
 		var true_stmt = parse_embedded_statement ();
 		Block false_stmt = null;
 		if (accept (TokenType.ELSE)) {
@@ -1870,19 +1862,19 @@ public class Vala.Genie.Parser : CodeVisitor {
 
 		expect (TokenType.EOL);
 
-		var stmt = new SwitchStatement (condition, get_src_com (begin));
+		var stmt = new SwitchStatement (condition, get_src (begin));
 		expect (TokenType.INDENT);
 		while (current () != TokenType.DEDENT) {
-			var section = new SwitchSection (get_src_com (begin));
+			var section = new SwitchSection (get_src (begin));
 			
 			if (accept (TokenType.WHEN)) {
 				do {
-					section.add_label (new SwitchLabel (parse_expression (), get_src_com (begin)));
+					section.add_label (new SwitchLabel (parse_expression (), get_src (begin)));
 				}
 				while (accept (TokenType.COMMA));
 			} else {
 				expect (TokenType.DEFAULT);
-				section.add_label (new SwitchLabel.with_default (get_src_com (begin)));
+				section.add_label (new SwitchLabel.with_default (get_src (begin)));
 			}
 
 			if (!accept (TokenType.EOL)) {
@@ -1892,7 +1884,7 @@ public class Vala.Genie.Parser : CodeVisitor {
 			parse_statements (section);
 
 			/* add break statement for each block */
-			var break_stmt =  new BreakStatement (get_src_com (begin));
+			var break_stmt =  new BreakStatement (get_src (begin));
 			section.add_statement (break_stmt);
 
 			stmt.add_section (section);
@@ -1913,7 +1905,7 @@ public class Vala.Genie.Parser : CodeVisitor {
 		}
 
 		var body = parse_embedded_statement ();
-		return new WhileStatement (condition, body, get_src_com (begin));
+		return new WhileStatement (condition, body, get_src (begin));
 	}
 
 	Statement parse_do_statement () throws ParseError {
@@ -1927,7 +1919,7 @@ public class Vala.Genie.Parser : CodeVisitor {
 
 		expect_terminator ();
 		
-		return new DoStatement (body, condition, get_src_com (begin));
+		return new DoStatement (body, condition, get_src (begin));
 	}
 
 
@@ -2008,7 +2000,7 @@ public class Vala.Genie.Parser : CodeVisitor {
 			expect (TokenType.DO);
 		}
 
-		var src = get_src_com (begin);
+		var src = get_src (begin);
 		var body = parse_embedded_statement ();
 		var stmt = new ForStatement (condition, body, src);
 
@@ -2046,7 +2038,7 @@ public class Vala.Genie.Parser : CodeVisitor {
 		if (!accept (TokenType.EOL)) {
 			expect (TokenType.DO);
 		}
-		var src = get_src_com (begin);
+		var src = get_src (begin);
 		var body = parse_embedded_statement ();
 		return new ForeachStatement (type, id, collection, body, src);
 	}
@@ -2055,14 +2047,14 @@ public class Vala.Genie.Parser : CodeVisitor {
 		var begin = get_location ();
 		expect (TokenType.BREAK);
 		expect_terminator ();
-		return new BreakStatement (get_src_com (begin));
+		return new BreakStatement (get_src (begin));
 	}
 
 	Statement parse_continue_statement () throws ParseError {
 		var begin = get_location ();
 		expect (TokenType.CONTINUE);
 		expect_terminator ();
-		return new ContinueStatement (get_src_com (begin));
+		return new ContinueStatement (get_src (begin));
 	}
 
 	Statement parse_return_statement () throws ParseError {
@@ -2073,7 +2065,7 @@ public class Vala.Genie.Parser : CodeVisitor {
 			expr = parse_expression ();
 		}
 		expect_terminator ();
-		return new ReturnStatement (expr, get_src_com (begin));
+		return new ReturnStatement (expr, get_src (begin));
 	}
 
 	Statement parse_yield_statement () throws ParseError {
@@ -2092,7 +2084,7 @@ public class Vala.Genie.Parser : CodeVisitor {
 		expect (TokenType.RAISE);
 		var expr = parse_expression ();
 		expect_terminator ();
-		return new ThrowStatement (expr, get_src_com (begin));
+		return new ThrowStatement (expr, get_src (begin));
 	}
 
 	Statement parse_try_statement () throws ParseError {
@@ -2110,7 +2102,7 @@ public class Vala.Genie.Parser : CodeVisitor {
 		} else {
 			finally_clause = parse_finally_clause ();
 		}
-		var stmt = new TryStatement (try_block, finally_clause, get_src_com (begin));
+		var stmt = new TryStatement (try_block, finally_clause, get_src (begin));
 		foreach (CatchClause clause in catch_clauses) {
 			stmt.add_catch_clause (clause);
 		}
@@ -2148,7 +2140,7 @@ public class Vala.Genie.Parser : CodeVisitor {
 		var expr = parse_expression ();
 		expect (TokenType.CLOSE_PARENS);
 		var stmt = parse_embedded_statement ();
-		return new LockStatement (expr, stmt, get_src_com (begin));
+		return new LockStatement (expr, stmt, get_src (begin));
 	}
 
 	Statement parse_delete_statement () throws ParseError {
@@ -2156,7 +2148,7 @@ public class Vala.Genie.Parser : CodeVisitor {
 		expect (TokenType.DELETE);
 		var expr = parse_expression ();
 		expect_terminator ();
-		return new DeleteStatement (expr, get_src_com (begin));
+		return new DeleteStatement (expr, get_src (begin));
 	}
 
 	Gee.List<Attribute>? parse_attributes () throws ParseError {
@@ -2347,7 +2339,11 @@ public class Vala.Genie.Parser : CodeVisitor {
 		var begin = get_location ();
 		expect (TokenType.NAMESPACE);
 		var sym = parse_symbol_name ();
-		var ns = new Namespace (sym.name, get_src_com (begin));
+		var ns = new Namespace (sym.name, get_src (begin));
+		if (comment != null) {
+			ns.add_comment (comment);
+			comment = null;
+		}
 		set_attributes (ns, attrs);
 		expect (TokenType.EOL);
 		parse_declarations (ns);
@@ -2453,7 +2449,7 @@ public class Vala.Genie.Parser : CodeVisitor {
 
 		accept (TokenType.EOL);
 
-		var cl = new Class (sym.name, get_src_com (begin));
+		var cl = new Class (sym.name, get_src (begin), comment);
 
 		if (ModifierFlags.PRIVATE in flags) {
 			cl.access = SymbolAccessibility.PRIVATE;
@@ -2572,7 +2568,7 @@ public class Vala.Genie.Parser : CodeVisitor {
 			array_type.element_type.value_owned = false;
 		}
 
-		var c = new Constant (id, type, initializer, get_src_com (begin));
+		var c = new Constant (id, type, initializer, get_src (begin), comment);
 		c.access = get_access (id);
 		
 		if (ModifierFlags.EXTERN in flags || scanner.source_file.external_package) {
@@ -2595,7 +2591,7 @@ public class Vala.Genie.Parser : CodeVisitor {
 
 		var type = parse_type ();
 
-		var f = new Field (id, type, null, get_src_com (begin));
+		var f = new Field (id, type, null, get_src (begin), comment);
 
 		if (ModifierFlags.ABSTRACT in flags || ModifierFlags.VIRTUAL in flags || ModifierFlags.OVERRIDE in flags) {
 			Report.error (f.source_reference, "abstract, virtual, and override modifiers are not applicable to fields");
@@ -2657,8 +2653,8 @@ public class Vala.Genie.Parser : CodeVisitor {
 		var begin = get_location ();
 		DataType type = new VoidType ();
 		expect (TokenType.INIT);
-		
-		var method = new Method (id, type, get_src_com (begin));
+
+		var method = new Method (id, type, get_src (begin), comment);
 		method.access = SymbolAccessibility.PUBLIC;
 		
 		set_attributes (method, attrs);
@@ -2704,15 +2700,13 @@ public class Vala.Genie.Parser : CodeVisitor {
 
 		expect (TokenType.CLOSE_PARENS);
 
-
 		/* deal with return value */
 		if (accept (TokenType.COLON)) {
 			type = parse_type ();
 			parse_type_parameter_list ();
 		}
 
-
-		var method = new Method (id, type, get_src_com (begin));
+		var method = new Method (id, type, get_src (begin), comment);
 		if (ModifierFlags.PRIVATE in flags) {
 			method.access = SymbolAccessibility.PRIVATE;
 		} else {
@@ -2844,7 +2838,7 @@ public class Vala.Genie.Parser : CodeVisitor {
 
 		var type = parse_type (false);
 
-		var prop = new Property (id, type, null, null, get_src_com (begin));
+		var prop = new Property (id, type, null, null, get_src (begin), comment);
 		if (ModifierFlags.PRIVATE in flags) {
 			prop.access = SymbolAccessibility.PRIVATE;
 		} else {
@@ -2993,7 +2987,7 @@ public class Vala.Genie.Parser : CodeVisitor {
 			type = new VoidType ();
 		}
 
-		var sig = new Vala.Signal (id, type, get_src_com (begin));
+		var sig = new Vala.Signal (id, type, get_src (begin), comment);
 		if (ModifierFlags.PRIVATE in flags) {
 			sig.access = SymbolAccessibility.PRIVATE;
 		} else {
@@ -3022,7 +3016,7 @@ public class Vala.Genie.Parser : CodeVisitor {
 		expect (TokenType.INIT);
 		var flags = parse_member_declaration_modifiers ();
 
-		var c = new Constructor (get_src_com (begin));
+		var c = new Constructor (get_src (begin));
 		if (ModifierFlags.STATIC in flags) {
 			c.binding = MemberBinding.STATIC;
 		} else if (ModifierFlags.CLASS in flags) {
@@ -3037,7 +3031,7 @@ public class Vala.Genie.Parser : CodeVisitor {
 	Destructor parse_destructor_declaration (Gee.List<Attribute>? attrs) throws ParseError {
 		var begin = get_location ();
 		expect (TokenType.FINAL);
-		var d = new Destructor (get_src_com (begin));
+		var d = new Destructor (get_src (begin));
 		accept_block ();
 		d.body = parse_block ();
 		return d;
@@ -3054,7 +3048,8 @@ public class Vala.Genie.Parser : CodeVisitor {
 		if (accept (TokenType.COLON)) {
 			base_type = parse_type ();
 		}
-		var st = new Struct (sym.name, get_src_com (begin));
+
+		var st = new Struct (sym.name, get_src (begin), comment);
 		if (ModifierFlags.PRIVATE in flags) {
 			st.access = SymbolAccessibility.PRIVATE;
 		} else {
@@ -3114,7 +3109,8 @@ public class Vala.Genie.Parser : CodeVisitor {
 				base_types.add (type);
 			} while (accept (TokenType.COMMA));
 		}
-		var iface = new Interface (sym.name, get_src_com (begin));
+
+		var iface = new Interface (sym.name, get_src (begin), comment);
 		if (ModifierFlags.PRIVATE in flags) {
 			iface.access = SymbolAccessibility.PRIVATE;
 		} else {
@@ -3180,8 +3176,8 @@ public class Vala.Genie.Parser : CodeVisitor {
 		expect (TokenType.ENUM);
 		var flags = parse_type_declaration_modifiers ();
 
-		var sym = parse_symbol_name (); 
-		var en = new Enum (sym.name, get_src_com (begin));
+		var sym = parse_symbol_name ();
+		var en = new Enum (sym.name, get_src (begin), comment);
 		if (ModifierFlags.PRIVATE in flags) {
 			en.access = SymbolAccessibility.PRIVATE;
 		} else {
@@ -3202,8 +3198,8 @@ public class Vala.Genie.Parser : CodeVisitor {
 			var value_attrs = parse_attributes ();
 			var value_begin = get_location (); 
 			string id = parse_identifier ();
-			
-			var ev = new EnumValue (id, get_src (value_begin));
+			comment = scanner.pop_comment ();
+			var ev = new EnumValue (id, get_src (value_begin), comment);
 			set_attributes (ev, value_attrs);
 			
 			if (accept (TokenType.ASSIGN)) {
@@ -3236,7 +3232,7 @@ public class Vala.Genie.Parser : CodeVisitor {
 		var flags = parse_type_declaration_modifiers ();
 
 		var sym = parse_symbol_name ();
-		var ed = new ErrorDomain (sym.name, get_src_com (begin));
+		var ed = new ErrorDomain (sym.name, get_src (begin), comment);
 		if (ModifierFlags.PRIVATE in flags) {
 			ed.access = SymbolAccessibility.PRIVATE;
 		} else {
@@ -3256,8 +3252,8 @@ public class Vala.Genie.Parser : CodeVisitor {
 			var code_attrs = parse_attributes ();
 			var code_begin = get_location ();
 			string id = parse_identifier ();
-
-			var ec = new ErrorCode (id, get_src (code_begin));
+			comment = scanner.pop_comment ();
+			var ec = new ErrorCode (id, get_src (code_begin), comment);
 			set_attributes (ec, code_attrs);
 			if (accept (TokenType.ASSIGN)) {
 				ec.value = parse_expression ();
@@ -3273,7 +3269,6 @@ public class Vala.Genie.Parser : CodeVisitor {
 		while (sym.inner != null) {
 			sym = sym.inner;
 			var ns = new Namespace (sym.name, ed.source_reference);
-			
 			if (result is Namespace) {
 				ns.add_namespace ((Namespace) result);
 			} else {
@@ -3404,26 +3399,24 @@ public class Vala.Genie.Parser : CodeVisitor {
 		expect (TokenType.CONSTRUCT);
 		parse_member_declaration_modifiers ();
 
-
 		if (accept (TokenType.OPEN_PARENS)) {
 			/* create default name using class name */
-			method = new CreationMethod (class_name, null, get_src_com (begin));
+			method = new CreationMethod (class_name, null, get_src (begin), comment);
 		} else {
 			var sym = parse_symbol_name ();
 			if (sym.inner == null) {
 			
 				if (sym.name != class_name) {
-					method = new CreationMethod (class_name, sym.name, get_src_com (begin));
+					method = new CreationMethod (class_name, sym.name, get_src (begin), comment);
 				} else {
-					method = new CreationMethod (sym.name, null, get_src_com (begin));
+					method = new CreationMethod (sym.name, null, get_src (begin), comment);
 				}
 			} else {
-				method = new CreationMethod (sym.inner.name, sym.name, get_src_com (begin));
+				method = new CreationMethod (sym.inner.name, sym.name, get_src (begin), comment);
 			}
 			expect (TokenType.OPEN_PARENS);
 		}
 
-
 		if (current () != TokenType.CLOSE_PARENS) {
 			do {
 				var param = parse_parameter ();
@@ -3486,7 +3479,7 @@ public class Vala.Genie.Parser : CodeVisitor {
 			type = new VoidType ();
 		}
 
-		var d = new Delegate (sym.name, type, get_src_com (begin));
+		var d = new Delegate (sym.name, type, get_src (begin), comment);
 
 		if (accept (TokenType.RAISES)) {
 			do {
@@ -3526,7 +3519,6 @@ public class Vala.Genie.Parser : CodeVisitor {
 		while (sym.inner != null) {
 			sym = sym.inner;
 			var ns = new Namespace (sym.name, d.source_reference);
-
 			if (result is Namespace) {
 				ns.add_namespace ((Namespace) result);
 			} else {
diff --git a/vala/valageniescanner.vala b/vala/valageniescanner.vala
index ecbb426a4..e39191c48 100644
--- a/vala/valageniescanner.vala
+++ b/vala/valageniescanner.vala
@@ -46,7 +46,7 @@ public class Vala.Genie.Scanner {
 	TokenType last_token;
 	bool parse_started;
 
-	string _comment;
+	Comment _comment;
 	
 	Conditional[] conditional_stack;
 
@@ -1039,14 +1039,11 @@ public class Vala.Genie.Scanner {
 		if (current[1] == '/') {
 			// single-line comment
 			current += 2;
-			char* begin = current;
-			
+
 			// skip until end of line or end of file
 			while (current < end && current[0] != '\n') {
 				current++;
 			}
-			
-			push_comment (((string) begin).ndup ((long) (current - begin)), line == 1);
 
 			/* do not ignore EOL if comment does not exclusively occupy the line */
 			if (current[0] == '\n' && last_token == TokenType.EOL) {
@@ -1057,6 +1054,12 @@ public class Vala.Genie.Scanner {
 			}
 		} else {
 			// delimited comment
+			SourceReference source_reference = null;
+
+			if (current[2] == '*') {
+				source_reference = new SourceReference (source_file, line, column, line, column);
+			}
+
 			current += 2;
 			char* begin = current;
 			int begin_line = line;
@@ -1073,7 +1076,12 @@ public class Vala.Genie.Scanner {
 				Report.error (new SourceReference (source_file, line, column, line, column), "syntax error, expected */");
 				return true;
 			}
-			push_comment (((string) begin).ndup ((long) (current - begin)), begin_line == 1);
+
+			if (source_reference != null) {
+				string comment = ((string) begin).ndup ((long) (current - begin));
+				push_comment (comment, source_reference, begin_line == 1 && comment[0] != '*');
+			}
+
 			current += 2;
 			column += 2;
 		}
@@ -1103,17 +1111,13 @@ public class Vala.Genie.Scanner {
 		}
 	}
 
-
-
-
-	void push_comment (string comment_item, bool file_comment) {
-		if (_comment == null) {
-			_comment = comment_item;
-		} else {
-			_comment = "%s\n%s".printf (_comment, comment_item);
+	void push_comment (string comment_item, SourceReference source_reference, bool file_comment) {
+		if (comment_item[0] == '*') {
+			_comment = new Comment (comment_item, source_reference);
 		}
+
 		if (file_comment) {
-			source_file.comment = _comment;
+			source_file.add_comment (new Comment (comment_item, source_reference));
 			_comment = null;
 		}
 	}
@@ -1123,23 +1127,17 @@ public class Vala.Genie.Scanner {
 	 *
 	 * @return saved comment
 	 */
-	public string? pop_comment () {
+	public Comment? pop_comment () {
 		if (_comment == null) {
 			return null;
 		}
 
-		var result_builder = new StringBuilder (_comment);
+		var comment = _comment;
 		_comment = null;
-
-		weak string index;
-		while ((index = result_builder.str.chr (-1, '\t')) != null) {
-			result_builder.erase (result_builder.str.pointer_to_offset (index), 1);
-		}
-
-		return result_builder.str;
+		return comment;
 	}
-	
-		bool pp_whitespace () {
+
+	bool pp_whitespace () {
 		bool found = false;
 		while (current < end && current[0].isspace () && current[0] != '\n') {
 			found = true;
diff --git a/vala/valainterface.vala b/vala/valainterface.vala
index 99664778c..44de8f6c2 100644
--- a/vala/valainterface.vala
+++ b/vala/valainterface.vala
@@ -88,8 +88,8 @@ public class Vala.Interface : ObjectTypeSymbol {
 	 * @param source reference to source code
 	 * @return       newly created interface
 	 */
-	public Interface (string name, SourceReference? source_reference = null) {
-		base (name, source_reference);
+	public Interface (string name, SourceReference? source_reference = null, Comment? comment = null) {
+		base (name, source_reference, comment);
 	}
 
 	/**
diff --git a/vala/valamember.vala b/vala/valamember.vala
index 8628d1a69..b0bdfafa7 100644
--- a/vala/valamember.vala
+++ b/vala/valamember.vala
@@ -27,6 +27,8 @@ using Gee;
  * Represents a general class member.
  */
 public abstract class Vala.Member : Symbol {
+	public Comment comment { get; set; }
+
 	private Gee.List<string> cheader_filenames = new ArrayList<string> ();
 
 	/**
@@ -35,8 +37,9 @@ public abstract class Vala.Member : Symbol {
 	 */
 	public bool hides { get; set; }
 
-	public Member (string? name, SourceReference? source_reference) {
+	public Member (string? name, SourceReference? source_reference, Comment? comment = null) {
 		base (name, source_reference);
+		this.comment = comment;
 	}
 
 	public override void accept (CodeVisitor visitor) {
diff --git a/vala/valamethod.vala b/vala/valamethod.vala
index 0d2190296..5c8119bd5 100644
--- a/vala/valamethod.vala
+++ b/vala/valamethod.vala
@@ -241,8 +241,8 @@ public class Vala.Method : Member {
 	 * @param source      reference to source code
 	 * @return            newly created method
 	 */
-	public Method (string? name, DataType return_type, SourceReference? source_reference = null) {
-		base (name, source_reference);
+	public Method (string? name, DataType return_type, SourceReference? source_reference = null, Comment? comment = null) {
+		base (name, source_reference, comment);
 		this.return_type = return_type;
 
 		carray_length_parameter_position = -3;
diff --git a/vala/valanamespace.vala b/vala/valanamespace.vala
index 14f93c451..7a31c8f89 100644
--- a/vala/valanamespace.vala
+++ b/vala/valanamespace.vala
@@ -37,6 +37,8 @@ public class Vala.Namespace : Symbol {
 	private Gee.List<Field> fields = new ArrayList<Field> ();
 	private Gee.List<Method> methods = new ArrayList<Method> ();
 
+	private Gee.List<Comment> comments = new ArrayList<Comment> ();
+
 	private Gee.List<string> cprefixes = new ArrayList<string> ();
 	private string lower_case_cprefix;
 	
@@ -56,6 +58,19 @@ public class Vala.Namespace : Symbol {
 		access = SymbolAccessibility.PUBLIC;
 	}
 	
+	public void add_comment (Comment comment) {
+		comments.add (comment);
+	}
+
+	/**
+	 * Returns a copy of the list of namespaces.
+	 *
+	 * @return comment list
+	 */
+	public Gee.List<Comment> get_comments () {
+		return new ReadOnlyList<Comment> (comments);
+	}
+
 	/**
 	 * Adds the specified namespace to this source file.
 	 *
@@ -68,6 +83,7 @@ public class Vala.Namespace : Symbol {
 			if (old_ns.external_package && !ns.external_package) {
 				old_ns.source_reference = ns.source_reference;
 			}
+
 			foreach (Namespace sub_ns in ns.get_namespaces ()) {
 				old_ns.add_namespace (sub_ns);
 			}
@@ -98,6 +114,9 @@ public class Vala.Namespace : Symbol {
 			foreach (Method m in ns.get_methods ()) {
 				old_ns.add_method (m);
 			}
+			foreach (Comment c in ns.get_comments ()) {
+				old_ns.add_comment (c);
+			}
 		} else {
 			namespaces.add (ns);
 			scope.add (ns.name, ns);
diff --git a/vala/valaobjecttypesymbol.vala b/vala/valaobjecttypesymbol.vala
index 752290c9f..b5c663276 100644
--- a/vala/valaobjecttypesymbol.vala
+++ b/vala/valaobjecttypesymbol.vala
@@ -32,8 +32,8 @@ using Gee;
 public abstract class Vala.ObjectTypeSymbol : TypeSymbol {
 	private Gee.List<TypeParameter> type_parameters = new ArrayList<TypeParameter> ();
 
-	public ObjectTypeSymbol (string name, SourceReference? source_reference = null) {
-		base (name, source_reference);
+	public ObjectTypeSymbol (string name, SourceReference? source_reference = null, Comment? comment = null) {
+		base (name, source_reference, comment);
 	}
 
 	public abstract Gee.List<Method> get_methods ();
diff --git a/vala/valaparser.vala b/vala/valaparser.vala
index 78d158120..569bff477 100644
--- a/vala/valaparser.vala
+++ b/vala/valaparser.vala
@@ -38,7 +38,7 @@ public class Vala.Parser : CodeVisitor {
 	// number of tokens in buffer
 	int size;
 
-	string comment;
+	Comment comment;
 
 	const int BUFFER_SIZE = 32;
 
@@ -147,14 +147,6 @@ public class Vala.Parser : CodeVisitor {
 		return new SourceReference (scanner.source_file, begin.line, begin.column, tokens[last_index].end.line, tokens[last_index].end.column);
 	}
 
-	SourceReference get_src_com (SourceLocation begin) {
-		int last_index = (index + BUFFER_SIZE - 1) % BUFFER_SIZE;
-
-		var src = new SourceReference.with_comment (scanner.source_file, begin.line, begin.column, tokens[last_index].end.line, tokens[last_index].end.column, comment);
-		comment = null;
-		return src;
-	}
-
 	SourceReference get_current_src () {
 		return new SourceReference (scanner.source_file, tokens[index].begin.line, tokens[index].begin.column, tokens[index].end.line, tokens[index].end.column);
 	}
@@ -308,12 +300,14 @@ public class Vala.Parser : CodeVisitor {
 
 	public void parse_file (SourceFile source_file) {
 		scanner = new Scanner (source_file);
+		parse_file_comments ();
 
 		index = -1;
 		size = 0;
 		
 		next ();
 
+
 		try {
 			parse_using_directives ();
 			parse_declarations (context.root, true);
@@ -324,6 +318,10 @@ public class Vala.Parser : CodeVisitor {
 		scanner = null;
 	}
 
+	void parse_file_comments () {
+		scanner.parse_file_comments ();
+	}
+
 	void skip_symbol_name () throws ParseError {
 		do {
 			skip_identifier ();
@@ -1249,6 +1247,7 @@ public class Vala.Parser : CodeVisitor {
 			try {
 				Statement stmt = null;
 				bool is_decl = false;
+
 				comment = scanner.pop_comment ();
 				switch (current ()) {
 				case TokenType.OPEN_BRACE:
@@ -1380,7 +1379,7 @@ public class Vala.Parser : CodeVisitor {
 
 		comment = scanner.pop_comment ();
 
-		var block = new Block (get_src_com (get_location ()));
+		var block = new Block (get_src (get_location ()));
 		block.add_statement (parse_embedded_statement_without_block ());
 		return block;
 
@@ -1410,7 +1409,7 @@ public class Vala.Parser : CodeVisitor {
 	Block parse_block () throws ParseError {
 		var begin = get_location ();
 		expect (TokenType.OPEN_BRACE);
-		var block = new Block (get_src_com (begin));
+		var block = new Block (get_src (begin));
 		parse_statements (block);
 		if (!accept (TokenType.CLOSE_BRACE)) {
 			// only report error if it's not a secondary error
@@ -1428,7 +1427,7 @@ public class Vala.Parser : CodeVisitor {
 	Statement parse_empty_statement () throws ParseError {
 		var begin = get_location ();
 		expect (TokenType.SEMICOLON);
-		return new EmptyStatement (get_src_com (begin));
+		return new EmptyStatement (get_src (begin));
 	}
 
 	void parse_local_variable_declarations (Block block) throws ParseError {
@@ -1459,14 +1458,14 @@ public class Vala.Parser : CodeVisitor {
 		if (accept (TokenType.ASSIGN)) {
 			initializer = parse_expression ();
 		}
-		return new LocalVariable (type, id, initializer, get_src_com (begin));
+		return new LocalVariable (type, id, initializer, get_src (begin));
 	}
 
 	Statement parse_expression_statement () throws ParseError {
 		var begin = get_location ();
 		var expr = parse_statement_expression ();
 		expect (TokenType.SEMICOLON);
-		return new ExpressionStatement (expr, get_src_com (begin));
+		return new ExpressionStatement (expr, get_src (begin));
 	}
 
 	Expression parse_statement_expression () throws ParseError {
@@ -1482,7 +1481,7 @@ public class Vala.Parser : CodeVisitor {
 		expect (TokenType.OPEN_PARENS);
 		var condition = parse_expression ();
 		expect (TokenType.CLOSE_PARENS);
-		var src = get_src_com (begin);
+		var src = get_src (begin);
 		var true_stmt = parse_embedded_statement ();
 		Block false_stmt = null;
 		if (accept (TokenType.ELSE)) {
@@ -1497,16 +1496,16 @@ public class Vala.Parser : CodeVisitor {
 		expect (TokenType.OPEN_PARENS);
 		var condition = parse_expression ();
 		expect (TokenType.CLOSE_PARENS);
-		var stmt = new SwitchStatement (condition, get_src_com (begin));
+		var stmt = new SwitchStatement (condition, get_src (begin));
 		expect (TokenType.OPEN_BRACE);
 		while (current () != TokenType.CLOSE_BRACE) {
-			var section = new SwitchSection (get_src_com (begin));
+			var section = new SwitchSection (get_src (begin));
 			do {
 				if (accept (TokenType.CASE)) {
-					section.add_label (new SwitchLabel (parse_expression (), get_src_com (begin)));
+					section.add_label (new SwitchLabel (parse_expression (), get_src (begin)));
 				} else {
 					expect (TokenType.DEFAULT);
-					section.add_label (new SwitchLabel.with_default (get_src_com (begin)));
+					section.add_label (new SwitchLabel.with_default (get_src (begin)));
 				}
 				expect (TokenType.COLON);
 			} while (current () == TokenType.CASE || current () == TokenType.DEFAULT);
@@ -1524,7 +1523,7 @@ public class Vala.Parser : CodeVisitor {
 		var condition = parse_expression ();
 		expect (TokenType.CLOSE_PARENS);
 		var body = parse_embedded_statement ();
-		return new WhileStatement (condition, body, get_src_com (begin));
+		return new WhileStatement (condition, body, get_src (begin));
 	}
 
 	Statement parse_do_statement () throws ParseError {
@@ -1536,7 +1535,7 @@ public class Vala.Parser : CodeVisitor {
 		var condition = parse_expression ();
 		expect (TokenType.CLOSE_PARENS);
 		expect (TokenType.SEMICOLON);
-		return new DoStatement (body, condition, get_src_com (begin));
+		return new DoStatement (body, condition, get_src (begin));
 	}
 
 	Statement parse_for_statement () throws ParseError {
@@ -1589,7 +1588,7 @@ public class Vala.Parser : CodeVisitor {
 			} while (accept (TokenType.COMMA));
 		}
 		expect (TokenType.CLOSE_PARENS);
-		var src = get_src_com (begin);
+		var src = get_src (begin);
 		var body = parse_embedded_statement ();
 		var stmt = new ForStatement (condition, body, src);
 		foreach (Expression init in initializer_list) {
@@ -1618,7 +1617,7 @@ public class Vala.Parser : CodeVisitor {
 		expect (TokenType.IN);
 		var collection = parse_expression ();
 		expect (TokenType.CLOSE_PARENS);
-		var src = get_src_com (begin);
+		var src = get_src (begin);
 		var body = parse_embedded_statement ();
 		return new ForeachStatement (type, id, collection, body, src);
 	}
@@ -1627,14 +1626,14 @@ public class Vala.Parser : CodeVisitor {
 		var begin = get_location ();
 		expect (TokenType.BREAK);
 		expect (TokenType.SEMICOLON);
-		return new BreakStatement (get_src_com (begin));
+		return new BreakStatement (get_src (begin));
 	}
 
 	Statement parse_continue_statement () throws ParseError {
 		var begin = get_location ();
 		expect (TokenType.CONTINUE);
 		expect (TokenType.SEMICOLON);
-		return new ContinueStatement (get_src_com (begin));
+		return new ContinueStatement (get_src (begin));
 	}
 
 	Statement parse_return_statement () throws ParseError {
@@ -1645,7 +1644,7 @@ public class Vala.Parser : CodeVisitor {
 			expr = parse_expression ();
 		}
 		expect (TokenType.SEMICOLON);
-		return new ReturnStatement (expr, get_src_com (begin));
+		return new ReturnStatement (expr, get_src (begin));
 	}
 
 	Statement parse_yield_statement () throws ParseError {
@@ -1664,7 +1663,7 @@ public class Vala.Parser : CodeVisitor {
 		expect (TokenType.THROW);
 		var expr = parse_expression ();
 		expect (TokenType.SEMICOLON);
-		return new ThrowStatement (expr, get_src_com (begin));
+		return new ThrowStatement (expr, get_src (begin));
 	}
 
 	Statement parse_try_statement () throws ParseError {
@@ -1681,7 +1680,7 @@ public class Vala.Parser : CodeVisitor {
 		} else {
 			finally_clause = parse_finally_clause ();
 		}
-		var stmt = new TryStatement (try_block, finally_clause, get_src_com (begin));
+		var stmt = new TryStatement (try_block, finally_clause, get_src (begin));
 		foreach (CatchClause clause in catch_clauses) {
 			stmt.add_catch_clause (clause);
 		}
@@ -1716,7 +1715,7 @@ public class Vala.Parser : CodeVisitor {
 		var expr = parse_expression ();
 		expect (TokenType.CLOSE_PARENS);
 		var stmt = parse_embedded_statement ();
-		return new LockStatement (expr, stmt, get_src_com (begin));
+		return new LockStatement (expr, stmt, get_src (begin));
 	}
 
 	Statement parse_delete_statement () throws ParseError {
@@ -1724,7 +1723,7 @@ public class Vala.Parser : CodeVisitor {
 		expect (TokenType.DELETE);
 		var expr = parse_expression ();
 		expect (TokenType.SEMICOLON);
-		return new DeleteStatement (expr, get_src_com (begin));
+		return new DeleteStatement (expr, get_src (begin));
 	}
 
 	Gee.List<Attribute>? parse_attributes () throws ParseError {
@@ -1939,7 +1938,12 @@ public class Vala.Parser : CodeVisitor {
 		var begin = get_location ();
 		expect (TokenType.NAMESPACE);
 		var sym = parse_symbol_name ();
-		var ns = new Namespace (sym.name, get_src_com (begin));
+		var ns = new Namespace (sym.name, get_src (begin));
+		if (comment != null) {
+			ns.add_comment (comment);
+			comment = null;
+		}
+
 		set_attributes (ns, attrs);
 		parse_declarations (ns);
 
@@ -2018,7 +2022,7 @@ public class Vala.Parser : CodeVisitor {
 			} while (accept (TokenType.COMMA));
 		}
 
-		var cl = new Class (sym.name, get_src_com (begin));
+		var cl = new Class (sym.name, get_src (begin), comment);
 		cl.access = access;
 		if (ModifierFlags.ABSTRACT in flags) {
 			cl.is_abstract = true;
@@ -2125,7 +2129,7 @@ public class Vala.Parser : CodeVisitor {
 			array_type.element_type.value_owned = false;
 		}
 
-		var c = new Constant (id, type, initializer, get_src_com (begin));
+		var c = new Constant (id, type, initializer, get_src (begin), comment);
 		c.access = access;
 		if (ModifierFlags.EXTERN in flags || scanner.source_file.external_package) {
 			c.external = true;
@@ -2146,7 +2150,7 @@ public class Vala.Parser : CodeVisitor {
 
 		type = parse_inline_array_type (type);
 
-		var f = new Field (id, type, null, get_src_com (begin));
+		var f = new Field (id, type, null, get_src (begin), comment);
 		f.access = access;
 		set_attributes (f, attrs);
 		if (ModifierFlags.STATIC in flags) {
@@ -2193,7 +2197,7 @@ public class Vala.Parser : CodeVisitor {
 		var type = parse_type ();
 		string id = parse_identifier ();
 		var type_param_list = parse_type_parameter_list ();
-		var method = new Method (id, type, get_src_com (begin));
+		var method = new Method (id, type, get_src (begin), comment);
 		method.access = access;
 		set_attributes (method, attrs);
 		foreach (TypeParameter type_param in type_param_list) {
@@ -2286,7 +2290,7 @@ public class Vala.Parser : CodeVisitor {
 		}
 
 		string id = parse_identifier ();
-		var prop = new Property (id, type, null, null, get_src_com (begin));
+		var prop = new Property (id, type, null, null, get_src (begin), comment);
 		prop.access = access;
 		set_attributes (prop, attrs);
 		if (ModifierFlags.STATIC in flags) {
@@ -2402,7 +2406,7 @@ public class Vala.Parser : CodeVisitor {
 		expect (TokenType.SIGNAL);
 		var type = parse_type ();
 		string id = parse_identifier ();
-		var sig = new Signal (id, type, get_src_com (begin));
+		var sig = new Signal (id, type, get_src (begin), comment);
 		sig.access = access;
 		set_attributes (sig, attrs);
 		if (ModifierFlags.VIRTUAL in flags) {
@@ -2433,7 +2437,7 @@ public class Vala.Parser : CodeVisitor {
 		if (ModifierFlags.NEW in flags) {
 			throw new ParseError.SYNTAX (get_error ("`new' modifier not allowed on constructor"));
 		}
-		var c = new Constructor (get_src_com (begin));
+		var c = new Constructor (get_src (begin));
 		if (ModifierFlags.STATIC in flags) {
 			c.binding = MemberBinding.STATIC;
 		} else if (ModifierFlags.CLASS in flags) {
@@ -2453,7 +2457,7 @@ public class Vala.Parser : CodeVisitor {
 		if (ModifierFlags.NEW in flags) {
 			throw new ParseError.SYNTAX (get_error ("`new' modifier not allowed on destructor"));
 		}
-		var d = new Destructor (get_src_com (begin));
+		var d = new Destructor (get_src (begin));
 		if (ModifierFlags.STATIC in flags) {
 			d.binding = MemberBinding.STATIC;
 		} else if (ModifierFlags.CLASS in flags) {
@@ -2474,7 +2478,7 @@ public class Vala.Parser : CodeVisitor {
 		if (accept (TokenType.COLON)) {
 			base_type = parse_type ();
 		}
-		var st = new Struct (sym.name, get_src_com (begin));
+		var st = new Struct (sym.name, get_src (begin), comment);
 		st.access = access;
 		if (ModifierFlags.EXTERN in flags || scanner.source_file.external_package) {
 			st.external = true;
@@ -2492,6 +2496,7 @@ public class Vala.Parser : CodeVisitor {
 		Symbol result = st;
 		while (sym.inner != null) {
 			sym = sym.inner;
+
 			var ns = new Namespace (sym.name, st.source_reference);
 			if (result is Namespace) {
 				ns.add_namespace ((Namespace) result);
@@ -2531,7 +2536,7 @@ public class Vala.Parser : CodeVisitor {
 				base_types.add (type);
 			} while (accept (TokenType.COMMA));
 		}
-		var iface = new Interface (sym.name, get_src_com (begin));
+		var iface = new Interface (sym.name, get_src (begin), comment);
 		iface.access = access;
 		if (ModifierFlags.EXTERN in flags || scanner.source_file.external_package) {
 			iface.external = true;
@@ -2590,7 +2595,7 @@ public class Vala.Parser : CodeVisitor {
 		var flags = parse_type_declaration_modifiers ();
 		expect (TokenType.ENUM);
 		var sym = parse_symbol_name ();
-		var en = new Enum (sym.name, get_src_com (begin));
+		var en = new Enum (sym.name, get_src (begin), comment);
 		en.access = access;
 		if (ModifierFlags.EXTERN in flags || scanner.source_file.external_package) {
 			en.external = true;
@@ -2607,7 +2612,8 @@ public class Vala.Parser : CodeVisitor {
 			var value_attrs = parse_attributes ();
 			var value_begin = get_location ();
 			string id = parse_identifier ();
-			var ev = new EnumValue (id, get_src (value_begin));
+			comment = scanner.pop_comment ();
+			var ev = new EnumValue (id, get_src (value_begin), comment);
 			set_attributes (ev, value_attrs);
 			if (accept (TokenType.ASSIGN)) {
 				ev.value = parse_expression ();
@@ -2648,7 +2654,7 @@ public class Vala.Parser : CodeVisitor {
 		var flags = parse_type_declaration_modifiers ();
 		expect (TokenType.ERRORDOMAIN);
 		var sym = parse_symbol_name ();
-		var ed = new ErrorDomain (sym.name, get_src_com (begin));
+		var ed = new ErrorDomain (sym.name, get_src (begin), comment);
 		ed.access = access;
 		if (ModifierFlags.EXTERN in flags || scanner.source_file.external_package) {
 			ed.external = true;
@@ -2665,7 +2671,8 @@ public class Vala.Parser : CodeVisitor {
 			var code_attrs = parse_attributes ();
 			var code_begin = get_location ();
 			string id = parse_identifier ();
-			var ec = new ErrorCode (id, get_src (code_begin));
+			comment = scanner.pop_comment ();
+			var ec = new ErrorCode (id, get_src (code_begin), comment);
 			set_attributes (ec, code_attrs);
 			if (accept (TokenType.ASSIGN)) {
 				ec.value = parse_expression ();
@@ -2827,9 +2834,9 @@ public class Vala.Parser : CodeVisitor {
 		}
 		CreationMethod method;
 		if (sym.inner == null) {
-			method = new CreationMethod (sym.name, null, get_src_com (begin));
+			method = new CreationMethod (sym.name, null, get_src (begin), comment);
 		} else {
-			method = new CreationMethod (sym.inner.name, sym.name, get_src_com (begin));
+			method = new CreationMethod (sym.inner.name, sym.name, get_src (begin), comment);
 		}
 		if (ModifierFlags.EXTERN in flags) {
 			method.external = true;
@@ -2876,7 +2883,7 @@ public class Vala.Parser : CodeVisitor {
 		var type = parse_type ();
 		var sym = parse_symbol_name ();
 		var type_param_list = parse_type_parameter_list ();
-		var d = new Delegate (sym.name, type, get_src_com (begin));
+		var d = new Delegate (sym.name, type, get_src (begin), comment);
 		d.access = access;
 		set_attributes (d, attrs);
 		if (ModifierFlags.STATIC in flags) {
diff --git a/vala/valaproperty.vala b/vala/valaproperty.vala
index 64eaa8ec1..7b7994971 100644
--- a/vala/valaproperty.vala
+++ b/vala/valaproperty.vala
@@ -199,8 +199,8 @@ public class Vala.Property : Member, Lockable {
 	 * @param source       reference to source code
 	 * @return             newly created property
 	 */
-	public Property (string name, DataType? property_type, PropertyAccessor? get_accessor, PropertyAccessor? set_accessor, SourceReference? source_reference = null) {
-		base (name, source_reference);
+	public Property (string name, DataType? property_type, PropertyAccessor? get_accessor, PropertyAccessor? set_accessor, SourceReference? source_reference = null, Comment? comment = null) {
+		base (name, source_reference, comment);
 		this.property_type = property_type;
 		this.get_accessor = get_accessor;
 		this.set_accessor = set_accessor;
diff --git a/vala/valascanner.vala b/vala/valascanner.vala
index a08bdaa91..a38c4804c 100644
--- a/vala/valascanner.vala
+++ b/vala/valascanner.vala
@@ -35,7 +35,7 @@ public class Vala.Scanner {
 	int line;
 	int column;
 
-	string _comment;
+	Comment _comment;
 
 	Conditional[] conditional_stack;
 
@@ -1076,7 +1076,7 @@ public class Vala.Scanner {
 		return found;
 	}
 
-	bool comment () {
+	bool comment (bool file_comment = false) {
 		if (current > end - 2
 		    || current[0] != '/'
 		    || (current[1] != '/' && current[1] != '*')) {
@@ -1084,19 +1084,37 @@ public class Vala.Scanner {
 		}
 
 		if (current[1] == '/') {
+			SourceReference source_reference = null;
+			if (file_comment) {
+				source_reference = new SourceReference (source_file, line, column, line, column);
+			}
+
 			// single-line comment
 			current += 2;
 			char* begin = current;
+
 			// skip until end of line or end of file
 			while (current < end && current[0] != '\n') {
 				current++;
 			}
-			push_comment (((string) begin).ndup ((long) (current - begin)), line == 1);
+
+			if (source_reference != null) {
+				push_comment (((string) begin).ndup ((long) (current - begin)), source_reference, file_comment);
+			}
 		} else {
-			// delimited comment
+			SourceReference source_reference = null;
+
+			if (file_comment && current[2] == '*') {
+				return false;
+			}
+
+			if (current[2] == '*' || file_comment) {
+				source_reference = new SourceReference (source_file, line, column, line, column);
+			}
+
 			current += 2;
+
 			char* begin = current;
-			int begin_line = line;
 			while (current < end - 1
 			       && (current[0] != '*' || current[1] != '/')) {
 				if (current[0] == '\n') {
@@ -1106,11 +1124,16 @@ public class Vala.Scanner {
 				current++;
 				column++;
 			}
+
 			if (current == end - 1) {
 				Report.error (new SourceReference (source_file, line, column, line, column), "syntax error, expected */");
 				return true;
 			}
-			push_comment (((string) begin).ndup ((long) (current - begin)), begin_line == 1);
+
+			if (source_reference != null) {
+				push_comment (((string) begin).ndup ((long) (current - begin)), source_reference, file_comment);
+			}
+
 			current += 2;
 			column += 2;
 		}
@@ -1123,37 +1146,35 @@ public class Vala.Scanner {
 		}
 	}
 
-	void push_comment (string comment_item, bool file_comment) {
-		if (_comment == null) {
-			_comment = comment_item;
-		} else {
-			_comment = "%s\n%s".printf (_comment, comment_item);
+	public void parse_file_comments () {
+		while (whitespace () || comment (true)) {
+		}
+	}
+
+	void push_comment (string comment_item, SourceReference source_reference, bool file_comment) {
+		if (comment_item[0] == '*') {
+			_comment = new Comment (comment_item, source_reference);
 		}
+
 		if (file_comment) {
-			source_file.comment = _comment;
+			source_file.add_comment (new Comment (comment_item, source_reference));
 			_comment = null;
 		}
 	}
-	
+
 	/**
 	 * Clears and returns the content of the comment stack.
 	 *
 	 * @return saved comment
 	 */
-	public string? pop_comment () {
+	public Comment? pop_comment () {
 		if (_comment == null) {
 			return null;
 		}
-		
-		var result_builder = new StringBuilder (_comment);
+
+		var comment = _comment;
 		_comment = null;
-		
-		string* index;
-		while ((index = result_builder.str.chr (-1, '\t')) != null) {
-			result_builder.erase ((long) (index - (string*) result_builder.str), 1);
-		}
-		
-		return result_builder.str;
+		return comment;
 	}
 }
 
diff --git a/vala/valasignal.vala b/vala/valasignal.vala
index 79ede7374..f51a92290 100644
--- a/vala/valasignal.vala
+++ b/vala/valasignal.vala
@@ -81,8 +81,8 @@ public class Vala.Signal : Member, Lockable {
 	 * @param source      reference to source code
 	 * @return            newly created signal
 	 */
-	public Signal (string name, DataType return_type, SourceReference? source_reference = null) {
-		base (name, source_reference);
+	public Signal (string name, DataType return_type, SourceReference? source_reference = null, Comment? comment = null) {
+		base (name, source_reference, comment);
 		this.return_type = return_type;
 	}
 	
diff --git a/vala/valasourcefile.vala b/vala/valasourcefile.vala
index 0ec442924..c85751767 100644
--- a/vala/valasourcefile.vala
+++ b/vala/valasourcefile.vala
@@ -32,10 +32,6 @@ public class Vala.SourceFile {
 	 */
 	public string filename { get; set; }
 	
-	/**
-	 * The header comment of this source file.
-	 */
-	public string comment { get; set; }
 	
 	/**
 	 * Specifies whether this file is a VAPI package file.
@@ -55,6 +51,8 @@ public class Vala.SourceFile {
 		}
 	}
 
+	private ArrayList<Comment> comments = new ArrayList<Comment> ();
+
 	private Gee.List<UsingDirective> using_directives = new ArrayList<UsingDirective> ();
 
 	private Gee.List<CodeNode> nodes = new ArrayList<CodeNode> ();
@@ -81,7 +79,23 @@ public class Vala.SourceFile {
 		this.context = context;
 		this.content = content;
 	}
-	
+
+	/**
+	 * Adds a header comment to this source file.
+	 */
+	public void add_comment (Comment comment) {
+		comments.add (comment);
+	}
+
+	/**
+	 * Returns a copy of the list of header comments.
+	 *
+	 * @return list of comments
+	 */
+	public Gee.List<Comment> get_comments () {
+		return new ReadOnlyList<Comment> (comments);
+	}
+
 	/**
 	 * Adds a new using directive with the specified namespace.
 	 *
diff --git a/vala/valasourcereference.vala b/vala/valasourcereference.vala
index fd3a0808f..4afe4d8a0 100644
--- a/vala/valasourcereference.vala
+++ b/vala/valasourcereference.vala
@@ -50,11 +50,6 @@ public class Vala.SourceReference {
 	 * The last column number of the referenced source code.
 	 */
 	public int last_column { get; set; }
-
-	/**
-	 * The text describing the referenced source code.
-	 */
-	public string comment { get; set; }
 	
 	/**
 	 * Creates a new source reference.
@@ -75,26 +70,6 @@ public class Vala.SourceReference {
 	}
 	
 	/**
-	 * Creates a new commented source reference.
-	 *
-	 * @param file         a source file
-	 * @param first_line   first line number
-	 * @param first_column first column number
-	 * @param last_line    last line number
-	 * @param last_column  last column number
-	 * @param comment      code comment
-	 * @return             newly created source reference
-	 */
-	public SourceReference.with_comment (SourceFile _file, int _first_line, int _first_column, int _last_line, int _last_column, string? _comment) {
-		file = _file;
-		first_line = _first_line;
-		first_column = _first_column;
-		last_line = _last_line;
-		last_column = _last_column;
-		comment = _comment;
-	}
-	
-	/**
 	 * Returns a string representation of this source reference.
 	 *
 	 * @return human-readable string
diff --git a/vala/valastruct.vala b/vala/valastruct.vala
index dd561834a..e060d8c79 100644
--- a/vala/valastruct.vala
+++ b/vala/valastruct.vala
@@ -102,8 +102,8 @@ public class Vala.Struct : TypeSymbol {
 	 * @param source_reference reference to source code
 	 * @return                 newly created struct
 	 */
-	public Struct (string name, SourceReference? source_reference = null) {
-		base (name, source_reference);
+	public Struct (string name, SourceReference? source_reference = null, Comment? comment = null) {
+		base (name, source_reference, comment);
 	}
 
 	/**
diff --git a/vala/valatypesymbol.vala b/vala/valatypesymbol.vala
index afaa1553f..df328d93e 100644
--- a/vala/valatypesymbol.vala
+++ b/vala/valatypesymbol.vala
@@ -29,10 +29,13 @@ using Gee;
  * code or imported from an external library with a Vala API file.
  */
 public abstract class Vala.TypeSymbol : Symbol {
+	public Comment? comment { get; set; }
+
 	private Gee.List<string> cheader_filenames = new ArrayList<string> ();
 
-	public TypeSymbol (string? name, SourceReference? source_reference = null) {
+	public TypeSymbol (string? name, SourceReference? source_reference = null, Comment? comment = null) {
 		base (name, source_reference);
+		this.comment = comment;
 	}
 
 	/**