Merge pull request #55 from candy-kingdom/feature/44-cref-fix

Refine `cref` handling
candy-kingdom · Dec 17, 2023 · d38d215 · d38d215
2 parents 3256f2a + b99212f
commit d38d215
Show file tree

Hide file tree

Showing 96 changed files with 922 additions and 385 deletions.
diff --git a/docs/DocCommentLink.md b/docs/DocCommentLink.md
diff --git a/docs/DocMethod.md b/docs/DocMethod.md
diff --git a/docs/DocType.md b/docs/DocType.md
diff --git a/docs/RenderMarkdownPipe.md b/docs/RenderMarkdownPipe.md
diff --git a/docs/Summary.Caching.CrefCache.md b/docs/Summary.Caching.CrefCache.md
@@ -0,0 +1,65 @@
+# [Summary.Caching.CrefCache](../src/Core/Caching/CrefCache.cs#L9)
+```cs
+public static partial class CrefCache
+```
+
+A cache of different `cref` conversions.
+
+## Methods
+### [AsCref(string)](../src/Core/Caching/CrefCache.cs#L30)
+```cs
+public static string AsCref(this string self)
+```
+
+Converts the given string into the format of `cref` attribute value.
+
+#### Example
+In the following example, the `"Some<T1, T2>"` string
+(which represents the name of some type)
+is converted into `"Some{T1,T2}"` as if it was a value of a link
+(e.g., <see cref="Some{T1,T2}">):
+```cs
+var a = "Some<T1, T2>";
+var b = a.AsCref();
+<br/>
+b.Should().Be("Some{T1,T2}");
+```
+
+### [AsRawCref(string)](../src/Core/Caching/CrefCache.cs#L51)
+```cs
+public static string AsRawCref(this string self)
+```
+
+Converts the given string into the format of `cref` attribute value
+but also removes all generic parameter names.
+
+#### Example
+In the following example, the `"Some<T1, T2>"` string
+(which represents the name of some type)
+is converted into `"Some{,}"`, the raw form of `cref` that can be used for comparisons
+without involving generic type parameter names.
+```cs
+var a = "Some<T1, T2>";
+var b = a.AsCref();
+<br/>
+b.Should().Be("Some{,}");
+```
+
+### [FromCref(string)](../src/Core/Caching/CrefCache.cs#L73)
+```cs
+public static string FromCref(this string self)
+```
+
+Converts the given string from the format of `cref` attribute value.
+
+#### Example
+In the following example, the `"Some{T1,T2}"` string
+(which represents the name of some type in the `cref` format)
+is converted into `"Some<T1, T2>` so that it can be displayed somewhere.
+```cs
+var a = "Some{T1,T2}";
+var b = a.AsCref();
+<br/>
+b.Should().Be("Some<T1, T2>");
+```
+
diff --git a/docs/ConsoleLoggerFactory.md → ...mmary.Cli.Logging.ConsoleLoggerFactory.md b/docs/ConsoleLoggerFactory.md → ...mmary.Cli.Logging.ConsoleLoggerFactory.md
diff --git a/docs/Doc.md → docs/Summary.Doc.md b/docs/Doc.md → docs/Summary.Doc.md
@@ -1,28 +1,28 @@
-# [Summary.Doc](../src/Core/Doc.cs#L7)
+# [Summary.Doc](../src/Core/Doc.cs#L9)
 ```cs
 public record Doc(DocMember[] Members)
 ```
 
 A document parsed from the source code or an assembly.
 
 ## Fields
-### [Empty](../src/Core/Doc.cs#L12)
+### [Empty](../src/Core/Doc.cs#L14)
 ```cs
 public static readonly Doc Empty
 ```
 
 An empty document.
 
 ## Properties
-### [Members](../src/Core/Doc.cs#L7)
+### [Members](../src/Core/Doc.cs#L9)
 ```cs
 public DocMember[] Members { get; }
 ```
 
 The sequence of members this doc contains.
 
 ## Methods
-### [Merge(Doc, Doc)](../src/Core/Doc.cs#L19)
+### [Merge(Doc, Doc)](../src/Core/Doc.cs#L21)
 ```cs
 public static Doc Merge(Doc a, Doc b)
 ```
@@ -33,7 +33,7 @@ Merges two documents together returning the new merged document.
 - `a`: The first document to merge.
 - `b`: The second document to merge.
 
-### [Declaration(DocType?<DocType>)](../src/Core/Doc.cs#L24)
+### [Declaration(DocType?<DocType>)](../src/Core/Doc.cs#L29)
 ```cs
 public DocTypeDeclaration? Declaration(DocType? type)
 ```

diff --git a/docs/DocComment.md → docs/Summary.DocComment.md b/docs/DocComment.md → docs/Summary.DocComment.md
diff --git a/docs/DocCommentElement.md → docs/Summary.DocCommentElement.md b/docs/DocCommentElement.md → docs/Summary.DocCommentElement.md
@@ -3,7 +3,7 @@
 public record DocCommentElement(string Name, DocCommentElementAttribute[] Attributes, DocCommentNode[] Nodes) : DocCommentNode
 ```
 
-A [`DocCommentNode`](./DocCommentNode.md) that represents a compound element (e.g. summary, remarks, and other XML elements).
+A [`DocCommentNode`](./Summary.DocCommentNode.md) that represents a compound element (e.g. summary, remarks, and other XML elements).
 
 _Each element can contain simple text as well as other elements._
 

diff --git a/docs/DocCommentElementAttribute.md → docs/Summary.DocCommentElementAttribute.md b/docs/DocCommentElementAttribute.md → docs/Summary.DocCommentElementAttribute.md
diff --git a/docs/DocCommentInheritDoc.md → docs/Summary.DocCommentInheritDoc.md b/docs/DocCommentInheritDoc.md → docs/Summary.DocCommentInheritDoc.md
@@ -3,7 +3,7 @@
 public record DocCommentInheritDoc(string? Cref) : DocCommentNode
 ```
 
-A [`DocCommentNode`](./DocCommentNode.md) that inherits documentation from another member
+A [`DocCommentNode`](./Summary.DocCommentNode.md) that inherits documentation from another member
 (`<inheritdoc>`).
 
 ## Properties

diff --git a/docs/Summary.DocCommentLink.md b/docs/Summary.DocCommentLink.md
@@ -0,0 +1,22 @@
+# [Summary.DocCommentLink](../src/Core/DocCommentLink.cs#L9)
+```cs
+public record DocCommentLink(DocMember? Member, string Value) : DocCommentNode
+```
+
+A [`DocCommentNode`](./Summary.DocCommentNode.md) that represents the link to other member (e.g. `<see cref="SomeMember"/>`).
+
+## Properties
+### [Member](../src/Core/DocCommentLink.cs#L9)
+```cs
+public DocMember? Member { get; }
+```
+
+The doc member the link references to.
+
+### [Value](../src/Core/DocCommentLink.cs#L9)
+```cs
+public string Value { get; }
+```
+
+The name of the member the link links to.
+
diff --git a/docs/DocCommentLiteral.md → docs/Summary.DocCommentLiteral.md b/docs/DocCommentLiteral.md → docs/Summary.DocCommentLiteral.md
@@ -3,7 +3,7 @@
 public record DocCommentLiteral(string Value, string LeadingTrivia = "") : DocCommentNode
 ```
 
-A [`DocCommentNode`](./DocCommentNode.md) that represents a literal value (e.g. text, space, newline character, etc.).
+A [`DocCommentNode`](./Summary.DocCommentNode.md) that represents a literal value (e.g. text, space, newline character, etc.).
 
 _Literals are simple tokens that are parsed as text._
 
@@ -28,5 +28,5 @@ The leading trivia of the literal that is not included in the `Value`(i.e. space
 public static DocCommentLiteral New(string value)
 ```
 
-Constructs a new [`DocCommentLiteral`](./DocCommentLiteral.md) from the given string.
+Constructs a new [`DocCommentLiteral`](./Summary.DocCommentLiteral.md) from the given string.
 
diff --git a/docs/DocCommentNode.md → docs/Summary.DocCommentNode.md b/docs/DocCommentNode.md → docs/Summary.DocCommentNode.md
diff --git a/docs/DocCommentParamRef.md → docs/Summary.DocCommentParamRef.md b/docs/DocCommentParamRef.md → docs/Summary.DocCommentParamRef.md
@@ -3,7 +3,7 @@
 public record DocCommentParamRef(string Value) : DocCommentNode
 ```
 
-A [`DocCommentNode`](./DocCommentNode.md) that represents the reference to a parameter
+A [`DocCommentNode`](./Summary.DocCommentNode.md) that represents the reference to a parameter
 (`<paramref>`, `<typeparamref>`).
 
 ## Properties

diff --git a/docs/DocDeprecation.md → docs/Summary.DocDeprecation.md b/docs/DocDeprecation.md → docs/Summary.DocDeprecation.md
diff --git a/docs/DocEvent.md → docs/Summary.DocEvent.md b/docs/DocEvent.md → docs/Summary.DocEvent.md
@@ -3,9 +3,9 @@
 public record DocEvent : DocMember
 ```
 
-A [`DocMember`](./DocMember.md) that represents a documented event in the parsed source code.
+A [`DocMember`](./Summary.DocMember.md) that represents a documented event in the parsed source code.
 
-_Similar to [`DocProperty`](./DocProperty.md) but with its own set of accessors._
+_Similar to [`DocProperty`](./Summary.DocProperty.md) but with its own set of accessors._
 
 ## Properties
 ### [Type](../src/Core/DocEvent.cs#L14)

diff --git a/docs/DocExtensions.md → docs/Summary.DocExtensions.md b/docs/DocExtensions.md → docs/Summary.DocExtensions.md
diff --git a/docs/DocField.md → docs/Summary.DocField.md b/docs/DocField.md → docs/Summary.DocField.md
@@ -3,7 +3,7 @@
 public record DocField : DocMember
 ```
 
-A [`DocMember`](./DocMember.md) that represents a documented field in the parsed source code.
+A [`DocMember`](./Summary.DocMember.md) that represents a documented field in the parsed source code.
 
 ## Properties
 ### [Type](../src/Core/DocField.cs#L11)

diff --git a/docs/DocIndexer.md → docs/Summary.DocIndexer.md b/docs/DocIndexer.md → docs/Summary.DocIndexer.md
@@ -3,7 +3,7 @@
 public record DocIndexer : DocProperty
 ```
 
-A [`DocProperty`](./DocProperty.md) that represents an indexer.
+A [`DocProperty`](./Summary.DocProperty.md) that represents an indexer.
 
 ## Properties
 ### [Params](../src/Core/DocIndexer.cs#L11)

diff --git a/docs/DocLocation.md → docs/Summary.DocLocation.md b/docs/DocLocation.md → docs/Summary.DocLocation.md