Merge pull request #53 from candy-kingdom/feature/52-render-exceptions

Render `<exception>`

docs/DocComment.md

@@ -71,5 +71,25 @@ public DocCommentElement? Element(Func<DocCommentElement, bool> p)
 A nested documentation element that matches the specified predicate `p`.
 
 #### Parameters
-- `p`: The predicate to apply on each nested documentation element.
+- `p`: The predicate to filter nested documentation elements.
+
+### [Elements(string)](../src/Core/DocComment.cs#L54)
+```cs
+public IEnumerable<DocCommentElement> Elements(string tag)
+```
+
+A sequence of nested documentation elements that have the specified name (e.g. `summary`, `remarks`, etc.).
+
+#### Parameters
+- `tag`: The name of the element tag to search inside the comment.
+
+### [Elements(Func<DocCommentElement, bool>)](../src/Core/DocComment.cs#L61)
+```cs
+public IEnumerable<DocCommentElement> Elements(Func<DocCommentElement, bool> p)
+```
+
+A sequence of nested documentation elements that match the specified predicate.
+
+#### Parameters
+- `p`: The predicate to filter nested documentation elements.
 

docs/Sample{T0,T1}.md

@@ -30,14 +30,14 @@ public void Delegate1(int x, int y)
 A sample delegate.
 
 ## Events
-### [Event1](../src/Core/Samples/Sample.cs#L91)
+### [Event1](../src/Core/Samples/Sample.cs#L92)
 ```cs
 public event Action Event1
 ```
 
 A sample field event.
 
-### [Event2](../src/Core/Samples/Sample.cs#L96)
+### [Event2](../src/Core/Samples/Sample.cs#L97)
 ```cs
 public Action Event2 { add; remove; }
 ```
@@ -92,22 +92,25 @@ public int Property2 { private get; set; }
 
 A sample property with custom visibility.
 
-### [Property3](../src/Core/Samples/Sample.cs#L70)
+### [Property3](../src/Core/Samples/Sample.cs#L71)
 ```cs
 public int Property3 { get; protected set; }
 ```
 
-A sample property with custom visibility (2).
+A sample property with custom visibility and an exception.
 
-### [Property4](../src/Core/Samples/Sample.cs#L75)
+#### Exceptions
+- `ArithmeticException`: Invalid number.
+
+### [Property4](../src/Core/Samples/Sample.cs#L76)
 ```cs
 public int Property4 { get; set; }
 ```
 
 A sample property with custom accessors.
 
 ## Indexers
-### [this[int]](../src/Core/Samples/Sample.cs#L86)
+### [this[int]](../src/Core/Samples/Sample.cs#L87)
 ```cs
 public int this[int i] { get; }
 ```
@@ -121,7 +124,7 @@ A sample indexer.
 What indexer returns.
 
 ## Methods
-### [Method<M0, M1, M2>(int, string)](../src/Core/Samples/Sample.cs#L118)
+### [Method<M0, M1, M2>(int, string)](../src/Core/Samples/Sample.cs#L121)
 ```cs
 public TimeSpan Method<M0, M1, M2>(int x, string y)
 ```
@@ -147,7 +150,11 @@ It contains three type parameters:
 #### Returns
 The `TimeSpan` instance.
 
-### [Method<M0, M1, M2>(short, string)](../src/Core/Samples/Sample.cs#L125)
+#### Exceptions
+- `ArgumentException`: The argument is incorrect.
+- `ApplicationException`: Something went wrong.
+
+### [Method<M0, M1, M2>(short, string)](../src/Core/Samples/Sample.cs#L128)
 ```cs
 public TimeSpan Method<M0, M1, M2>(short x, string y)
 ```
@@ -166,3 +173,7 @@ The overloaded [`Method{M0,M1,M2}(int,string)`](./Method{M0,M1,M2}(int,string).m
 #### Returns
 The `TimeSpan` instance.
 
+#### Exceptions
+- `ArgumentException`: The argument is incorrect.
+- `ApplicationException`: Something went wrong.
+

src/Core/DocComment.cs

@@ -43,7 +43,21 @@ public record DocComment(DocCommentNode[] Nodes)
     /// <summary>
     ///     A nested documentation element that matches the specified predicate <c>p</c>.
     /// </summary>
-    /// <param name="p">The predicate to apply on each nested documentation element.</param>
+    /// <param name="p">The predicate to filter nested documentation elements.</param>
     public DocCommentElement? Element(Func<DocCommentElement, bool> p) =>
-        Nodes.OfType<DocCommentElement>().FirstOrDefault(p);
+        Elements(p).FirstOrDefault();
+
+    /// <summary>
+    ///     A sequence of nested documentation elements that have the specified name (e.g. <c>summary</c>, <c>remarks</c>, etc.).
+    /// </summary>
+    /// <param name="tag">The name of the element tag to search inside the comment.</param>
+    public IEnumerable<DocCommentElement> Elements(string tag) =>
+        Elements(x => x.Name == tag);
+
+    /// <summary>
+    ///     A sequence of nested documentation elements that match the specified predicate.
+    /// </summary>
+    /// <param name="p">The predicate to filter nested documentation elements.</param>
+    public IEnumerable<DocCommentElement> Elements(Func<DocCommentElement, bool> p) =>
+        Nodes.OfType<DocCommentElement>().Where(p);
 }

src/Core/Samples/Sample.cs

@@ -65,8 +65,9 @@ public class Child
     public int Property2 { private get; set; }
 
     /// <summary>
-    ///     A sample property with custom visibility (2).
+    ///     A sample property with custom visibility and an exception.
     /// </summary>
+    /// <exception cref="ArithmeticException">Invalid number.</exception>
     public int Property3 { get; protected set; }
 
     /// <summary>
@@ -115,6 +116,8 @@ public event Action Event2
     /// <typeparam name="M1">The second type parameter of the method.</typeparam>
     /// <typeparam name="M2">The third type parameter of the method.</typeparam>
     /// <returns>The <c>TimeSpan</c> instance.</returns>
+    /// <exception cref="ArgumentException">The argument is incorrect.</exception>
+    /// <exception cref="ApplicationException">Something went wrong.</exception>
     public TimeSpan Method<M0, M1, M2>(int x, string y) =>
         TimeSpan.Zero;
 

src/Plugins/Markdown/MdRenderer.cs

@@ -69,22 +69,30 @@ private MdRenderer Method(DocMethod method) => this
         .Header(method)
         .TypeParams(method)
         .Params(method)
-        .Returns(method.Comment);
+        .Returns(method.Comment)
+        .Exceptions(method.Comment);
 
     private MdRenderer Property(DocTypeDeclaration parent, DocProperty property)
     {
         if (property.Generated)
             return this
                 .Name(property)
                 .Declaration(property)
-                .Element(parent.Comment.Param(property.Name));
+                .Element(parent.Comment.Param(property.Name))
+                .Exceptions(property.Comment);
 
         if (property is DocIndexer indexer)
             return Indexer(indexer);
 
-        return Header(property);
+        return Header(property).Exceptions(property.Comment);
     }
 
+    private MdRenderer Indexer(DocIndexer indexer) => this
+        .Header(indexer)
+        .Params(indexer)
+        .Returns(indexer.Comment)
+        .Exceptions(indexer.Comment);
+
     private MdRenderer Header(DocMember member) => this
         .Name(member)
         .Deprecation(member.Deprecation)
@@ -93,12 +101,6 @@ private MdRenderer Header(DocMember member) => this
         .Element(member.Comment.Element("remarks"), x => $"_{x}_")
         .Elements("Example", member.Comment.Element("example"));
 
-    private MdRenderer Indexer(DocIndexer indexer) => this
-        .Header(indexer)
-        .Params(indexer)
-        .Returns(indexer.Comment);
-
-    // TODO: We can omit rendering `Name` and render `Declaration` only but it'd be nice to make this customizable via plugins.
     private MdRenderer Name(DocMember member)
     {
         return member switch
@@ -187,6 +189,9 @@ private MdRenderer Members<T>(string section, DocTypeDeclaration type, IEnumerab
     private MdRenderer Returns(DocComment comment) =>
         Elements("Returns", comment.Element("returns"));
 
+    private MdRenderer Exceptions(DocComment comment) =>
+        Params("Exceptions", comment.Elements("exception").Select(x => (x.Attribute("cref")?.Value ?? " ", x))!);
+
     private MdRenderer Elements(string section, DocCommentElement? element, Func<string, string>? map = null) =>
         element is null ? this : Section(section).Element(element, map);
 

src/Plugins/Roslyn/CSharp/Extensions/XmlSyntaxExtensions.cs

@@ -76,7 +76,7 @@ private static string Name(this XmlEmptyElementSyntax self) =>
     private static DocCommentElementAttribute? Attribute(this XmlAttributeSyntax self) => self switch
     {
         XmlNameAttributeSyntax name => new DocCommentElementAttribute(self.Name.ToString(), name.Identifier.Identifier.ValueText),
-
+        XmlCrefAttributeSyntax cref => new DocCommentElementAttribute(self.Name.ToString(), cref.Cref.ToString()),
         _ => null,
     };