fix docs

Author: elringus

src/cs/Bootsharp.Publish.Test/GenerateJS/DeclarationTest.cs

@@ -1434,7 +1434,7 @@ public enum Kind
             }
 
             /// <summary>
-            /// A payload sent across interop.
+            /// A payload sent across interop, keyed by <c>Kind</c>.
             /// </summary>
             /// <remarks>Visible in generated TypeScript.</remarks>
             public record Payload<T>
@@ -1461,7 +1461,7 @@ public interface IExportedInstanced
                 /// <summary>Current state.</summary>
                 int State { get; }
 
-                /// <summary>Invokes instance.</summary>
+                /// <summary>Invokes instance with <paramref name="value"/>.</summary>
                 /// <param name="value">Value to pass.</param>
                 void Inv (string value);
             }
@@ -1485,7 +1485,10 @@ public partial class Class
                 /// <summary>Runs foo.</summary>
                 /// <param name="function">Function value.</param>
                 /// <param name="names">Names to run.</param>
-                /// <returns>Computed value.</returns>
+                /// <returns>
+                /// Computed value to be used with <see cref="Get"/> and <see cref="OnFoo"/>,
+                /// or <see langword="null"/> when invalid.
+                /// </returns>
                 [Export] public static int Foo (List<int?> function, string[] names) => 0;
 
                 /// <summary>Gets payload.</summary>
@@ -1522,7 +1525,7 @@ export enum Kind {
         Contains(
             """
             /**
-             * A payload sent across interop.
+             * A payload sent across interop, keyed by Kind.
              */
             export type Payload<T> = Readonly<{
                 /**
@@ -1542,7 +1545,7 @@ export interface IExportedInstanced {
                  */
                 readonly state: number;
                 /**
-                 * Invokes instance.
+                 * Invokes instance with value.
                  * @param value Value to pass.
                  */
                 inv(value: string): void;
@@ -1578,7 +1581,7 @@ export namespace Class {
                  * Runs foo.
                  * @param fn Function value.
                  * @param names Names to run.
-                 * @returns Computed value.
+                 * @returns Computed value to be used with Get and OnFoo, or null when invalid.
                  */
                 export function foo(fn: Array<number | null>, names: Array<string>): number;
                 /**

src/cs/Bootsharp.Publish/GenerateJS/Declarations/DocumentationBuilder.cs

@@ -1,4 +1,5 @@
 using System.Reflection;
+using System.Text.RegularExpressions;
 using System.Xml.Linq;
 
 namespace Bootsharp.Publish;
@@ -34,7 +35,7 @@ public void Event (EventMeta evt)
         var sum = GetSummary(xml);
         foreach (var arg in evt.Args)
             if ((GetArgXml(xml, arg) ?? GetDelegateArgXml(arg)) is { } x)
-                sum.Add($"@param {arg.JSName} {x.Value}");
+                sum.Add($"@param {arg.JSName} {RenderXml(x)}");
         Append(sum);
 
         XElement? GetDelegateArgXml (ArgumentMeta arg)
@@ -61,9 +62,9 @@ public void Method (MethodMeta method)
         var sum = GetSummary(xml);
         foreach (var arg in method.Args)
             if (GetArgXml(xml, arg) is { } x)
-                sum.Add($"@param {arg.JSName} {x.Value}");
+                sum.Add($"@param {arg.JSName} {RenderXml(x)}");
         if (xml.Element("returns") is { } returns)
-            sum.Add($"@returns {returns.Value}");
+            sum.Add($"@returns {RenderXml(returns)}");
         Append(sum);
 
         static string GetMethodKey (MethodMeta method)
@@ -113,6 +114,15 @@ private static string GetXmlKey (Type type)
 
     private static List<string> GetSummary (XElement xml)
     {
-        return xml.Elements("summary").Select(e => e.Value.Trim()).ToList();
+        return xml.Elements("summary").Select(RenderXml).ToList();
     }
+
+    private static string RenderXml (XElement xml) =>
+        Regex.Replace(string.Concat(xml.DescendantNodes().Select(node => node switch {
+            XText xt => xt.Value,
+            XElement xe when xe.Attribute("cref")?.Value is { } cref =>
+                Regex.Replace(Regex.Replace(cref, "[`(].*$", ""), "^.*[.:]", ""),
+            XElement xe when (xe.Attribute("langword") ?? xe.Attribute("name"))?.Value is { } v => v,
+            _ => ""
+        })), @"\s+", " ").Trim();
 }