Skip to content

Commit

Permalink
feat: add @example supports
Browse files Browse the repository at this point in the history
[converter][web]
  • Loading branch information
MangelMaxime committed May 2, 2024
1 parent 60e6f3c commit fd66863
Show file tree
Hide file tree
Showing 13 changed files with 149 additions and 2 deletions.
1 change: 1 addition & 0 deletions src/Glutinum.Converter/FsharpAST.fs
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,7 @@ type FSharpXmlDoc =
| Returns of string
| Remarks of string
| DefaultValue of string
| Example of string

[<RequireQualifiedAccess>]
type FSharpLiteral =
Expand Down
1 change: 1 addition & 0 deletions src/Glutinum.Converter/GlueAST.fs
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,7 @@ type GlueComment =
| Deprecated of string option
| Remarks of string
| DefaultValue of string
| Example of string

type GlueParameter =
{
Expand Down
24 changes: 22 additions & 2 deletions src/Glutinum.Converter/Printer.fs
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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) =
Expand Down
9 changes: 9 additions & 0 deletions src/Glutinum.Converter/Reader/Documentation.fs
Original file line number Diff line number Diff line change
Expand Up @@ -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

)
Expand Down
1 change: 1 addition & 0 deletions src/Glutinum.Converter/Transform.fs
Original file line number Diff line number Diff line change
Expand Up @@ -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
)

{|
Expand Down
4 changes: 4 additions & 0 deletions src/Glutinum.Web/Pages/Editors.FSharpAST.FSharpASTViewer.fs
Original file line number Diff line number Diff line change
Expand Up @@ -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"

Expand Down
4 changes: 4 additions & 0 deletions src/Glutinum.Web/Pages/Editors.GlueAST.GlueASTViewer.fs
Original file line number Diff line number Diff line change
Expand Up @@ -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
)
Expand Down
Original file line number Diff line number Diff line change
@@ -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;
21 changes: 21 additions & 0 deletions tests/specs/references/documentation/example/codeBlockWithLang.fsx
Original file line number Diff line number Diff line change
@@ -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"
(***)
16 changes: 16 additions & 0 deletions tests/specs/references/documentation/example/multiple.d.ts
Original file line number Diff line number Diff line change
@@ -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;
31 changes: 31 additions & 0 deletions tests/specs/references/documentation/example/multiple.fsx
Original file line number Diff line number Diff line change
@@ -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"
(***)
9 changes: 9 additions & 0 deletions tests/specs/references/documentation/example/single.d.ts
Original file line number Diff line number Diff line change
@@ -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;
21 changes: 21 additions & 0 deletions tests/specs/references/documentation/example/single.fsx
Original file line number Diff line number Diff line change
@@ -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"
(***)

0 comments on commit fd66863

Please sign in to comment.