From 059e54c99c766c9f09d453e9aac296b9e988833c Mon Sep 17 00:00:00 2001
From: Maxime Mangel <mangel.maxime@protonmail.com>
Date: Tue, 7 May 2024 15:35:44 +0200
Subject: [PATCH] feat: add `@link` supports

[converter]
---
 src/Glutinum.Converter/Printer.fs             | 27 ++++++++++++++++---
 .../link/dontCrashNonUrlFormat.d.ts           |  8 ++++++
 .../link/dontCrashNonUrlFormat.fsx            | 21 +++++++++++++++
 .../documentation/link/urlOnly.d.ts           |  7 +++++
 .../references/documentation/link/urlOnly.fsx | 20 ++++++++++++++
 .../documentation/link/urlWithLabel.d.ts      |  7 +++++
 .../documentation/link/urlWithLabel.fsx       | 20 ++++++++++++++
 7 files changed, 107 insertions(+), 3 deletions(-)
 create mode 100644 tests/specs/references/documentation/link/dontCrashNonUrlFormat.d.ts
 create mode 100644 tests/specs/references/documentation/link/dontCrashNonUrlFormat.fsx
 create mode 100644 tests/specs/references/documentation/link/urlOnly.d.ts
 create mode 100644 tests/specs/references/documentation/link/urlOnly.fsx
 create mode 100644 tests/specs/references/documentation/link/urlWithLabel.d.ts
 create mode 100644 tests/specs/references/documentation/link/urlWithLabel.fsx

diff --git a/src/Glutinum.Converter/Printer.fs b/src/Glutinum.Converter/Printer.fs
index 56e67bd..c15f73a 100644
--- a/src/Glutinum.Converter/Printer.fs
+++ b/src/Glutinum.Converter/Printer.fs
@@ -280,10 +280,10 @@ let private codeInline (line: string) =
     Regex("`(?<code>[^`]*)`")
         .Replace(line, (fun m -> $"""<c>{m.Groups.["code"].Value}</c>"""))
 
-let private codeBlock (line: string) =
+let private codeBlock (text: string) =
     Regex("```(?<lang>\S*)(?<code>[^`]+)```", RegexOptions.Multiline)
         .Replace(
-            line,
+            text,
             (fun m ->
                 let lang = m.Groups.["lang"].Value
                 let code = m.Groups.["code"].Value
@@ -295,7 +295,28 @@ let private codeBlock (line: string) =
             )
         )
 
-let private transformToXmlDoc (line: string) = line |> codeBlock |> codeInline
+let private link (text: string) =
+    // tsdoc link format is {@link link|customText}
+    // However when getting the text after `getDocumentationComment` and `displayPartsToString`
+    // the `|` seems to be replaced by a space
+    // Regex below tries to handle both cases
+    Regex("\{@link\s+(?<link>[^\s}|]+)\s*((\|)?\s*(?<customText>[^}]+))?\}")
+        .Replace(
+            text,
+            (fun m ->
+                let link = m.Groups.["link"].Value.Trim()
+                let customText = m.Groups.["customText"].Value
+
+                if String.IsNullOrWhiteSpace customText then
+                    $"""<see href="{link}">{link}</see>"""
+                else
+                    let customText = customText.Trim()
+                    $"""<see href="{link}">{customText}</see>" """.TrimEnd()
+            )
+        )
+
+let private transformToXmlDoc (line: string) =
+    line |> codeBlock |> codeInline |> link
 
 let private printBlockTag
     (printer: Printer)
diff --git a/tests/specs/references/documentation/link/dontCrashNonUrlFormat.d.ts b/tests/specs/references/documentation/link/dontCrashNonUrlFormat.d.ts
new file mode 100644
index 0000000..2002af2
--- /dev/null
+++ b/tests/specs/references/documentation/link/dontCrashNonUrlFormat.d.ts
@@ -0,0 +1,8 @@
+/**
+ * Links can point to a URL:
+ *
+ * {@link my-control-library#Button }
+ * {@link my-control-library#Button | the Button class}
+ * {@link @microsoft/my-control-library/lib/Button#Button | the Button class}
+ */
+declare function isInlineTag(tagName: string): boolean;
diff --git a/tests/specs/references/documentation/link/dontCrashNonUrlFormat.fsx b/tests/specs/references/documentation/link/dontCrashNonUrlFormat.fsx
new file mode 100644
index 0000000..1f8a2fa
--- /dev/null
+++ b/tests/specs/references/documentation/link/dontCrashNonUrlFormat.fsx
@@ -0,0 +1,21 @@
+module rec Glutinum
+
+open Fable.Core
+open Fable.Core.JsInterop
+open System
+
+[<Erase>]
+type Exports =
+    /// <summary>
+    /// Links can point to a URL:
+    /// 
+    /// <see href="my-control-library#Button">my-control-library#Button</see>
+    /// <see href="my-control-library#Button">the Button class</see>"
+    /// <see href="@microsoft/my-control-library/lib/Button#Button">the Button class</see>"
+    /// </summary>
+    [<Import("isInlineTag", "module")>]
+    static member isInlineTag (tagName: string) : bool = nativeOnly
+
+(***)
+#r "nuget: Fable.Core"
+(***)
diff --git a/tests/specs/references/documentation/link/urlOnly.d.ts b/tests/specs/references/documentation/link/urlOnly.d.ts
new file mode 100644
index 0000000..7d2fd2d
--- /dev/null
+++ b/tests/specs/references/documentation/link/urlOnly.d.ts
@@ -0,0 +1,7 @@
+/**
+ * Links can point to a URL:
+ *
+ * {@link https://github.com/microsoft/tsdoc}
+ * {@link https://github.com/microsoft/tsdoc }
+ */
+declare function isInlineTag(tagName: string): boolean;
diff --git a/tests/specs/references/documentation/link/urlOnly.fsx b/tests/specs/references/documentation/link/urlOnly.fsx
new file mode 100644
index 0000000..bc7c58a
--- /dev/null
+++ b/tests/specs/references/documentation/link/urlOnly.fsx
@@ -0,0 +1,20 @@
+module rec Glutinum
+
+open Fable.Core
+open Fable.Core.JsInterop
+open System
+
+[<Erase>]
+type Exports =
+    /// <summary>
+    /// Links can point to a URL:
+    /// 
+    /// <see href="https://github.com/microsoft/tsdoc">https://github.com/microsoft/tsdoc</see>
+    /// <see href="https://github.com/microsoft/tsdoc">https://github.com/microsoft/tsdoc</see>
+    /// </summary>
+    [<Import("isInlineTag", "module")>]
+    static member isInlineTag (tagName: string) : bool = nativeOnly
+
+(***)
+#r "nuget: Fable.Core"
+(***)
diff --git a/tests/specs/references/documentation/link/urlWithLabel.d.ts b/tests/specs/references/documentation/link/urlWithLabel.d.ts
new file mode 100644
index 0000000..e93ef8d
--- /dev/null
+++ b/tests/specs/references/documentation/link/urlWithLabel.d.ts
@@ -0,0 +1,7 @@
+/**
+ * Links can point to a URL:
+ *
+ * {@link https://github.com/microsoft/tsdoc | TSDoc}
+ * {@link https://github.com/microsoft/tsdoc |   TSDoc   }
+ */
+declare function isInlineTag(tagName: string): boolean;
diff --git a/tests/specs/references/documentation/link/urlWithLabel.fsx b/tests/specs/references/documentation/link/urlWithLabel.fsx
new file mode 100644
index 0000000..d16df13
--- /dev/null
+++ b/tests/specs/references/documentation/link/urlWithLabel.fsx
@@ -0,0 +1,20 @@
+module rec Glutinum
+
+open Fable.Core
+open Fable.Core.JsInterop
+open System
+
+[<Erase>]
+type Exports =
+    /// <summary>
+    /// Links can point to a URL:
+    /// 
+    /// <see href="https://github.com/microsoft/tsdoc">TSDoc</see>"
+    /// <see href="https://github.com/microsoft/tsdoc">TSDoc</see>"
+    /// </summary>
+    [<Import("isInlineTag", "module")>]
+    static member isInlineTag (tagName: string) : bool = nativeOnly
+
+(***)
+#r "nuget: Fable.Core"
+(***)