feat: add @example supports

[converter][web]

src/Glutinum.Converter/FsharpAST.fs

@@ -11,6 +11,7 @@ type FSharpXmlDoc =
     | Returns of string
     | Remarks of string
     | DefaultValue of string
+    | Example of string
 
 [<RequireQualifiedAccess>]
 type FSharpLiteral =

src/Glutinum.Converter/GlueAST.fs

@@ -22,6 +22,7 @@ type GlueComment =
     | Deprecated of string option
     | Remarks of string
     | DefaultValue of string
+    | Example of string
 
 type GlueParameter =
     {

src/Glutinum.Converter/Printer.fs

@@ -275,11 +275,27 @@ module FSharpAccessibility =
         | FSharpAccessibility.Private -> printer.WriteInline("private ")
         | FSharpAccessibility.Protected -> printer.WriteInline("protected ")
 
+// Comment adaptation should be moved in the transform phase
 let private codeInline (line: string) =
     Regex("`(?<code>[^`]*)`")
         .Replace(line, (fun m -> $"""<c>{m.Groups.["code"].Value}</c>"""))
 
-let private transformToXmlDoc (line: string) = line |> codeInline
+let private codeBlock (line: string) =
+    Regex("```(?<lang>\S*)(?<code>[^`]+)```", RegexOptions.Multiline)
+        .Replace(
+            line,
+            (fun m ->
+                let lang = m.Groups.["lang"].Value
+                let code = m.Groups.["code"].Value
+
+                if String.IsNullOrWhiteSpace lang then
+                    $"""<code>{code}</code>"""
+                else
+                    $"""<code lang="{lang}">{code}</code>"""
+            )
+        )
+
+let private transformToXmlDoc (line: string) = line |> codeBlock |> codeInline
 
 let private printBlockTag
     (printer: Printer)
@@ -323,7 +339,8 @@ let private printXmlDoc (printer: Printer) (elements: FSharpXmlDoc list) =
             | FSharpXmlDoc.DefaultValue _ -> true
             | FSharpXmlDoc.Returns _
             | FSharpXmlDoc.Param _
-            | FSharpXmlDoc.Remarks _ -> false
+            | FSharpXmlDoc.Remarks _
+            | FSharpXmlDoc.Example _ -> false
         )
 
     // Print the summary first
@@ -358,6 +375,9 @@ let private printXmlDoc (printer: Printer) (elements: FSharpXmlDoc list) =
 
         | FSharpXmlDoc.Remarks content ->
             printBlockTag printer "remarks" [] content
+
+        | FSharpXmlDoc.Example content ->
+            printBlockTag printer "example" [] content
     )
 
 let private printInterface (printer: Printer) (interfaceInfo: FSharpInterface) =

src/Glutinum.Converter/Reader/Documentation.fs

@@ -81,6 +81,15 @@ let private readDocumentation
                         |> Some
                     | None -> None
 
+                | "example" ->
+                    match tag.comment with
+                    | Some comment ->
+                        ts.getTextOfJSDocComment comment
+                        |> Option.defaultValue ""
+                        |> GlueComment.Example
+                        |> Some
+                    | None -> None
+
                 | _ -> None
 
         )

src/Glutinum.Converter/Transform.fs

@@ -126,6 +126,7 @@ let private transformComment (comment: GlueAST.GlueComment list) =
             | GlueComment.Remarks remarks -> FSharpXmlDoc.Remarks remarks
             | GlueComment.DefaultValue defaultValue ->
                 FSharpXmlDoc.DefaultValue defaultValue
+            | GlueComment.Example example -> FSharpXmlDoc.Example example
         )
 
     {|

src/Glutinum.Web/Pages/Editors.FSharpAST.FSharpASTViewer.fs

@@ -200,6 +200,10 @@ type FSharpASTViewer =
             | FSharpXmlDoc.DefaultValue content ->
                 [ ASTViewer.renderValueOnly content ]
                 |> ASTViewer.renderNode "DefaultValue"
+
+            | FSharpXmlDoc.Example content ->
+                [ ASTViewer.renderValueOnly content ]
+                |> ASTViewer.renderNode "Example"
         )
         |> ASTViewer.renderNode "XmlDoc"
 

src/Glutinum.Web/Pages/Editors.GlueAST.GlueASTViewer.fs

@@ -95,6 +95,10 @@ type GlueASTViewer =
                 [ ASTViewer.renderValueOnly content ]
                 |> ASTViewer.renderNode "Remarks"
 
+            | GlueComment.Example content ->
+                [ ASTViewer.renderValueOnly content ]
+                |> ASTViewer.renderNode "Example"
+
             | GlueComment.Deprecated content ->
                 ASTViewer.renderKeyValueOption "Deprecated" id content
         )

tests/specs/references/documentation/example/codeBlockWithLang.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @example
+ * Here's an example with negative numbers:
+ * ```js
+ * // Prints "0":
+ * console.log(add(1,-1));
+ * ```
+ */
+declare function isInlineTag(tagName: string): boolean;

tests/specs/references/documentation/example/codeBlockWithLang.fsx

@@ -0,0 +1,21 @@
+module rec Glutinum
+
+open Fable.Core
+open Fable.Core.JsInterop
+open System
+
+[<Erase>]
+type Exports =
+    /// <example>
+    /// Here's an example with negative numbers:
+    /// <code lang="js">
+    /// // Prints "0":
+    /// console.log(add(1,-1));
+    /// </code>
+    /// </example>
+    [<Import("isInlineTag", "module")>]
+    static member isInlineTag (tagName: string) : bool = nativeOnly
+
+(***)
+#r "nuget: Fable.Core"
+(***)

tests/specs/references/documentation/example/multiple.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Adds two numbers together.
+ * @example
+ * Here's a simple example:
+ * ```
+ * // Prints "2":
+ * console.log(add(1,1));
+ * ```
+ * @example
+ * Here's an example with negative numbers:
+ * ```
+ * // Prints "0":
+ * console.log(add(1,-1));
+ * ```
+ */
+declare function add(a: number, b: number): number;

tests/specs/references/documentation/example/multiple.fsx

@@ -0,0 +1,31 @@
+module rec Glutinum
+
+open Fable.Core
+open Fable.Core.JsInterop
+open System
+
+[<Erase>]
+type Exports =
+    /// <summary>
+    /// Adds two numbers together.
+    /// </summary>
+    /// <example>
+    /// Here's a simple example:
+    /// <code>
+    /// // Prints "2":
+    /// console.log(add(1,1));
+    /// </code>
+    /// </example>
+    /// <example>
+    /// Here's an example with negative numbers:
+    /// <code>
+    /// // Prints "0":
+    /// console.log(add(1,-1));
+    /// </code>
+    /// </example>
+    [<Import("add", "module")>]
+    static member add (a: float, b: float) : float = nativeOnly
+
+(***)
+#r "nuget: Fable.Core"
+(***)

tests/specs/references/documentation/example/single.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @example
+ * Here's an example with negative numbers:
+ * ```
+ * // Prints "0":
+ * console.log(add(1,-1));
+ * ```
+ */
+declare function isInlineTag(tagName: string): boolean;

tests/specs/references/documentation/example/single.fsx

@@ -0,0 +1,21 @@
+module rec Glutinum
+
+open Fable.Core
+open Fable.Core.JsInterop
+open System
+
+[<Erase>]
+type Exports =
+    /// <example>
+    /// Here's an example with negative numbers:
+    /// <code>
+    /// // Prints "0":
+    /// console.log(add(1,-1));
+    /// </code>
+    /// </example>
+    [<Import("isInlineTag", "module")>]
+    static member isInlineTag (tagName: string) : bool = nativeOnly
+
+(***)
+#r "nuget: Fable.Core"
+(***)