Added <example /> support

Currently just treats the content of an <example /> element as a <pre
/>, which works for basic cases but might look weird if people are
nesting paragraphs and such in their examples.

src/Docu.Console/Docu.csproj

@@ -3,7 +3,7 @@
   <PropertyGroup>
     <Configuration Condition=" '$(Configuration)' == '' ">Debug</Configuration>
     <Platform Condition=" '$(Platform)' == '' ">AnyCPU</Platform>
-    <ProductVersion>9.0.21022</ProductVersion>
+    <ProductVersion>9.0.30729</ProductVersion>
     <SchemaVersion>2.0</SchemaVersion>
     <ProjectGuid>{2FB9E7C3-B602-4343-B510-9C8DBFC7B8FD}</ProjectGuid>
     <OutputType>Exe</OutputType>
@@ -71,6 +71,7 @@
     <Compile Include="Console\Switch.cs" />
     <Compile Include="Documentation\Comments\BaseComment.cs" />
     <Compile Include="Documentation\Comments\InlineList.cs" />
+    <Compile Include="Documentation\Comments\MultilineCode.cs" />
     <Compile Include="Documentation\Comments\ParameterReference.cs" />
     <Compile Include="Documentation\Comments\Remarks.cs" />
     <Compile Include="Documentation\Comments\Summary.cs" />
@@ -129,6 +130,7 @@
     <Compile Include="Parsing\Comments\MultilineCodeCommentParser.cs" />
     <Compile Include="Parsing\Comments\ParagraphCommentParser.cs" />
     <Compile Include="Parsing\Comments\ParameterReferenceParser.cs" />
+    <Compile Include="Parsing\Comments\ParseOptions.cs" />
     <Compile Include="Parsing\Comments\SeeCodeCommentParser.cs" />
     <Compile Include="Parsing\DocumentationXmlMatcher.cs" />
     <Compile Include="Parsing\DocumentableMemberFinder.cs" />
@@ -266,6 +268,14 @@
       <CopyToOutputDirectory>Always</CopyToOutputDirectory>
     </Content>
   </ItemGroup>
+  <ItemGroup>
+    <Content Include="templates\!namespace\_example.spark">
+      <CopyToOutputDirectory>Always</CopyToOutputDirectory>
+    </Content>
+    <Content Include="templates\js\example.js">
+      <CopyToOutputDirectory>Always</CopyToOutputDirectory>
+    </Content>
+  </ItemGroup>
   <Import Project="$(MSBuildToolsPath)\Microsoft.CSharp.targets" />
   <!-- To modify your build process, add your task inside one of the targets below and uncomment it. 
        Other similar extension points exist, see Microsoft.Common.targets.

src/Docu.Console/Documentation/BaseDocumentationElement.cs

@@ -17,6 +17,7 @@ protected BaseDocumentationElement(Identifier identifier)
             Summary = new Summary();
             Remarks = new Remarks();
             Value = new Value();
+            Example = new MultilineCode();
         }
 
         public virtual bool HasDocumentation
@@ -30,6 +31,7 @@ public virtual bool HasDocumentation
         public Summary Summary { get; set; }
         public Remarks Remarks { get; set; }
         public Value Value { get; set; }
+        public MultilineCode Example { get; set; }
 
         public bool IsIdentifiedBy(Identifier otherIdentifier)
         {

src/Docu.Console/Documentation/Comments/IComment.cs

@@ -5,5 +5,6 @@ namespace Docu.Documentation.Comments
     public interface IComment
     {
         IEnumerable<IComment> Children { get; }
+        void AddChild(IComment child);
     }
 }

src/Docu.Console/Documentation/Comments/MultilineCode.cs

@@ -0,0 +1,15 @@
+using System.Collections.Generic;
+
+namespace Docu.Documentation.Comments
+{
+    public class MultilineCode : BaseComment
+    {
+        public MultilineCode()
+        {}
+
+        public MultilineCode(IEnumerable<IComment> comments)
+        {
+            comments.ForEach(AddChild);
+        }
+    }
+}

src/Docu.Console/Documentation/DeclaredType.cs

@@ -1,7 +1,5 @@
 using System;
 using System.Collections.Generic;
-using System.Linq;
-using Docu.Documentation.Comments;
 using Docu.Parsing.Model;
 
 namespace Docu.Documentation

src/Docu.Console/Documentation/Generators/BaseGenerator.cs

@@ -60,6 +60,16 @@ protected void ParseRemarks(IDocumentationMember member, IDocumentationElement d
                 doc.Remarks = new Remarks(commentParser.ParseNode(node));
         }
 
+        protected void ParseExample(IDocumentationMember member, IDocumentationElement doc)
+        {
+            if (member.Xml == null) return;
+
+            var node = member.Xml.SelectSingleNode("example");
+
+            if (node != null)
+                doc.Example = new MultilineCode(commentParser.ParseNode(node, new ParseOptions { PreserveWhitespace = true }));
+        }
+
         protected void ParseReturns(IDocumentationMember member, Method doc)
         {
             if (member.Xml == null) return;
@@ -70,6 +80,7 @@ protected void ParseReturns(IDocumentationMember member, Method doc)
                 doc.Returns = new Summary(commentParser.ParseNode(node));
         }
 
+
         protected Namespace FindNamespace(IDocumentationMember association, List<Namespace> namespaces)
         {
             var identifier = Identifier.FromNamespace(association.TargetType.Namespace);

src/Docu.Console/Documentation/Generators/EventGenerator.cs

@@ -25,6 +25,7 @@ public void Add(List<Namespace> namespaces, DocumentedEvent association)
 
             ParseSummary(association, doc);
             ParseRemarks(association, doc);
+            ParseExample(association, doc);
 
             matchedAssociations.Add(association.Name, doc);
             type.AddEvent(doc);

src/Docu.Console/Documentation/Generators/FieldGenerator.cs

@@ -28,6 +28,7 @@ public void Add(List<Namespace> namespaces, DocumentedField association)
 
             ParseSummary(association, doc);
             ParseRemarks(association, doc);
+            ParseExample(association, doc);
 
             matchedAssociations.Add(association.Name, doc);
             type.AddField(doc);

src/Docu.Console/Documentation/Generators/MethodGenerator.cs

@@ -33,6 +33,7 @@ public void Add(List<Namespace> namespaces, DocumentedMethod association)
             ParseRemarks(association, doc);
             ParseValue(association, doc);
             ParseReturns(association, doc);
+            ParseExample(association, doc);
 
             foreach (var parameter in association.Method.GetParameters())
             {

src/Docu.Console/Documentation/Generators/PropertyGenerator.cs

@@ -32,6 +32,7 @@ public void Add(List<Namespace> namespaces, DocumentedProperty association)
             ParseSummary(association, doc);
             ParseValue(association, doc);
             ParseRemarks(association, doc);
+            ParseExample(association, doc);
 
             if (matchedAssociations.ContainsKey(association.Name))
                 return;

src/Docu.Console/Documentation/Generators/TypeGenerator.cs

@@ -22,6 +22,7 @@ public void Add(List<Namespace> namespaces, DocumentedType association)
             ParseSummary(association, doc);
             ParseRemarks(association, doc);
             ParseValue(association, doc);
+            ParseExample(association, doc);
 
             if (matchedAssociations.ContainsKey(association.Name)) return;
 

src/Docu.Console/Documentation/IDocumentationElement.cs

@@ -12,6 +12,7 @@ public interface IDocumentationElement
         Summary Summary { get; set; }
         Remarks Remarks { get; set; }
         Value Value { get; set; }
+        MultilineCode Example { get; set; }
         bool IsIdentifiedBy(Identifier otherIdentifier);
         void ConvertToExternalReference();
     }

src/Docu.Console/Extensions.cs

@@ -1,5 +1,6 @@
 using System;
 using System.Collections.Generic;
+using System.Linq;
 using System.Text.RegularExpressions;
 
 namespace Docu
@@ -42,5 +43,52 @@ public static string TrimComment(this string text, bool first, bool last)
 
             return prepared;
         }
+
+        public static string[] SplitByNewLine(this string text)
+        {
+            return text.Split(new[] { Environment.NewLine }, StringSplitOptions.None);
+        }
+
+        public static string JoinIntoString(this IEnumerable<string> items)
+        {
+            return items.JoinIntoString("");
+        }
+
+        public static string JoinIntoString(this IEnumerable<string> items, string separator)
+        {
+            return string.Join(separator, items.ToArray());
+        }
+
+        public static string NormaliseIndent(this string text)
+        {
+            var whitespaceRegexp = new Regex(@"^([\s]+)", RegexOptions.Compiled);
+            var lines = text.SplitByNewLine();
+
+            lines = RemoveBlankOrWhitespaceLinesAtStart(lines);
+            lines = RemoveBlankOrWhitespaceLinesAtEnd(lines);
+
+            var removableWhitespaceCharCount =
+                lines
+                    .Select(x => whitespaceRegexp.Match(x).Groups[0].Length)
+                    .Min();
+
+            return lines
+                .Select(x => x.Substring(removableWhitespaceCharCount))
+                .JoinIntoString("\r\n");
+        }
+
+        static string[] RemoveBlankOrWhitespaceLinesAtEnd(IEnumerable<string> lines)
+        {
+            return RemoveBlankOrWhitespaceLinesAtStart(lines.Reverse())
+                .Reverse()
+                .ToArray();
+        }
+
+        static string[] RemoveBlankOrWhitespaceLinesAtStart(IEnumerable<string> lines)
+        {
+            return lines
+                .SkipWhile(x => x.Trim() == "")
+                .ToArray();
+        }
     }
 }

src/Docu.Console/Output/Rendering/HtmlOutputFormatter.cs

@@ -23,6 +23,7 @@ public HtmlOutputFormatter(IDocuTemplate view)
                 new OutputFormatterPart<See>(FormatSee),
                 new OutputFormatterPart<InlineText>(FormatInlineText),
                 new OutputFormatterPart<InlineCode>(FormatInlineCode),
+                new OutputFormatterPart<MultilineCode>(FormatMultilineCode),
                 new OutputFormatterPart<Paragraph>(FormatParagraph),
                 new OutputFormatterPart<ParameterReference>(FormatParameterReference),
                 new OutputFormatterPart<DefinitionList>(FormatDefinitionList),
@@ -196,6 +197,11 @@ private string FormatInlineCode(InlineCode block)
             return "<code>" + block.Text + "</code>";
         }
 
+        private string FormatMultilineCode(MultilineCode block)
+        {
+            return FormatGeneralContainer(block);
+        }
+
         public string NamespaceUrlFormat { get; set; }
         public string TypeUrlFormat { get; set; }
         public string MethodUrlFormat { get; set; }

src/Docu.Console/Parsing/Comments/CommentParser.cs

@@ -1,4 +1,5 @@
-using System.Collections.Generic;
+using System;
+using System.Collections.Generic;
 using System.Xml;
 using Docu.Documentation.Comments;
 using System.Linq;
@@ -15,6 +16,11 @@ public CommentParser(ICommentNodeParser[] parsers)
         }
 
         public IList<IComment> Parse(XmlNodeList nodes)
+        {
+            return Parse(nodes, new ParseOptions());
+        }
+
+        public IList<IComment> Parse(XmlNodeList nodes, ParseOptions options)
         {
             var blocks = new List<IComment>();
 
@@ -28,7 +34,7 @@ public IList<IComment> Parse(XmlNodeList nodes)
                 var parser = _parsers.FirstOrDefault(p => p.CanParse(node));
                 if (parser == null) continue;
 
-                var block = parser.Parse(this, node, first, last);
+                var block = parser.Parse(this, node, first, last, options);
                 if (block != null)
                 {
                     blocks.Add(block);
@@ -39,10 +45,15 @@ public IList<IComment> Parse(XmlNodeList nodes)
         }
 
         public IList<IComment> ParseNode(XmlNode node)
+        {
+            return ParseNode(node, new ParseOptions());
+        }
+
+        public IList<IComment> ParseNode(XmlNode node, ParseOptions options)
         {
             var blocks = new List<IComment>();
 
-            blocks.AddRange(Parse(node.ChildNodes));
+            blocks.AddRange(Parse(node.ChildNodes, options));
 
             return blocks.AsReadOnly();
         }

src/Docu.Console/Parsing/Comments/ICommentNodeParser.cs

@@ -6,6 +6,6 @@ namespace Docu.Parsing.Comments
     public interface ICommentNodeParser
     {
         bool CanParse(XmlNode node);
-        IComment Parse(ICommentParser parser, XmlNode node, bool first, bool last);
+        IComment Parse(ICommentParser parser, XmlNode node, bool first, bool last, ParseOptions options);
     }
 }

src/Docu.Console/Parsing/Comments/ICommentParser.cs

@@ -7,6 +7,8 @@ namespace Docu.Parsing.Comments
     public interface ICommentParser
     {
         IList<IComment> Parse(XmlNodeList nodes);
+        IList<IComment> Parse(XmlNodeList nodes, ParseOptions options);
         IList<IComment> ParseNode(XmlNode node);
+        IList<IComment> ParseNode(XmlNode node, ParseOptions options);
     }
 }

src/Docu.Console/Parsing/Comments/InlineCodeCommentParser.cs

@@ -10,7 +10,7 @@ public bool CanParse(XmlNode node)
             return node.Name == "c";
         }
 
-        public IComment Parse(ICommentParser parser, XmlNode node, bool first, bool last)
+        public IComment Parse(ICommentParser parser, XmlNode node, bool first, bool last, ParseOptions options)
         {
             return new InlineCode(node.InnerText.TrimComment(first, last));
         }

src/Docu.Console/Parsing/Comments/InlineListCommentParser.cs

@@ -10,7 +10,7 @@ public bool CanParse(XmlNode node)
             return node.Name == "list";
         }
 
-        public IComment Parse(ICommentParser parser, XmlNode node, bool first, bool last)
+        public IComment Parse(ICommentParser parser, XmlNode node, bool first, bool last, ParseOptions options)
         {
             var typeAttribute = node.Attributes["type"];
             var listTypeName = typeAttribute == null ? string.Empty : typeAttribute.Value;

src/Docu.Console/Parsing/Comments/InlineTextCommentParser.cs

@@ -10,8 +10,11 @@ public bool CanParse(XmlNode node)
             return node is XmlText;
         }
 
-        public IComment Parse(ICommentParser parser, XmlNode node, bool first, bool last)
+        public IComment Parse(ICommentParser parser, XmlNode node, bool first, bool last, ParseOptions options)
         {
+            if (options.PreserveWhitespace)
+                return new InlineText(node.InnerText.NormaliseIndent());
+
             return new InlineText(node.InnerText.TrimComment(first, last));
         }
     }

src/Docu.Console/Parsing/Comments/MultilineCodeCommentParser.cs

@@ -10,7 +10,7 @@ public bool CanParse(XmlNode node)
             return node.Name == "code";
         }
 
-        public IComment Parse(ICommentParser parser, XmlNode node, bool first, bool last)
+        public IComment Parse(ICommentParser parser, XmlNode node, bool first, bool last, ParseOptions options)
         {
             return new InlineCode(node.InnerText.TrimComment(true, true));
         }

src/Docu.Console/Parsing/Comments/ParagraphCommentParser.cs

@@ -10,7 +10,7 @@ public bool CanParse(XmlNode node)
             return node.Name == "para";
         }
 
-        public IComment Parse(ICommentParser parser, XmlNode node, bool first, bool last)
+        public IComment Parse(ICommentParser parser, XmlNode node, bool first, bool last, ParseOptions options)
         {
             return new Paragraph(parser.Parse(node.ChildNodes));
         }

src/Docu.Console/Parsing/Comments/ParameterReferenceParser.cs

@@ -10,7 +10,7 @@ public bool CanParse(XmlNode node)
             return node.Name == "paramref";
         }
 
-        public IComment Parse(ICommentParser parser, XmlNode node, bool first, bool last)
+        public IComment Parse(ICommentParser parser, XmlNode node, bool first, bool last, ParseOptions options)
         {
             var attribute = node.Attributes["name"];
             var parameterName = attribute == null ? string.Empty : attribute.Value;

src/Docu.Console/Parsing/Comments/ParseOptions.cs

@@ -0,0 +1,12 @@
+namespace Docu.Parsing.Comments
+{
+    public class ParseOptions
+    {
+        public bool PreserveWhitespace { get; set; }
+
+        public ParseOptions()
+        {
+            PreserveWhitespace = false;
+        }
+    }
+}

src/Docu.Console/Parsing/Comments/SeeCodeCommentParser.cs

@@ -12,7 +12,7 @@ public bool CanParse(XmlNode node)
             return node.Name == "see";
         }
 
-        public IComment Parse(ICommentParser parser, XmlNode node, bool first, bool last)
+        public IComment Parse(ICommentParser parser, XmlNode node, bool first, bool last, ParseOptions options)
         {
             IReferencable reference = new NullReference();
             if (node.Attributes["cref"] == null) return new See(reference);