From 5801cc5cad8324a114d08733fafa31f7632d1118 Mon Sep 17 00:00:00 2001
From: ST-DDT <ST-DDT@gmx.de>
Date: Fri, 21 Jun 2024 11:41:03 +0200
Subject: [PATCH] docs: separate signature and examples (#2962)

---
 docs/.vitepress/components/api-docs/method.ts  | 1 +
 docs/.vitepress/components/api-docs/method.vue | 3 +++
 scripts/apidocs/output/page.ts                 | 3 ++-
 3 files changed, 6 insertions(+), 1 deletion(-)

diff --git a/docs/.vitepress/components/api-docs/method.ts b/docs/.vitepress/components/api-docs/method.ts
index 90310ed01d7..4da480b806e 100644
--- a/docs/.vitepress/components/api-docs/method.ts
+++ b/docs/.vitepress/components/api-docs/method.ts
@@ -6,6 +6,7 @@ export interface ApiDocsMethod {
   readonly parameters: ApiDocsMethodParameter[];
   readonly returns: string;
   readonly throws: string | undefined; // HTML
+  readonly signature: string; // HTML
   readonly examples: string; // HTML
   readonly seeAlsos: string[];
   readonly sourcePath: string; // URL-Suffix
diff --git a/docs/.vitepress/components/api-docs/method.vue b/docs/.vitepress/components/api-docs/method.vue
index 8e25e8f8607..5cd819e9612 100644
--- a/docs/.vitepress/components/api-docs/method.vue
+++ b/docs/.vitepress/components/api-docs/method.vue
@@ -40,6 +40,9 @@ function seeAlsoToUrl(see: string): string {
       <strong>Throws:</strong> <span v-html="props.method.throws" />
     </p>
 
+    <div v-html="props.method.signature" />
+
+    <h3>Examples</h3>
     <div v-html="props.method.examples" />
 
     <div v-if="props.method.seeAlsos.length > 0">
diff --git a/scripts/apidocs/output/page.ts b/scripts/apidocs/output/page.ts
index 9f3c87f7973..c00ba4d23ad 100644
--- a/scripts/apidocs/output/page.ts
+++ b/scripts/apidocs/output/page.ts
@@ -165,7 +165,8 @@ async function toMethodData(method: RawApiDocsMethod): Promise<ApiDocsMethod> {
     sourcePath: `${filePath}#L${line}`,
     throws: throws.length === 0 ? undefined : mdToHtml(throws.join('\n'), true),
     returns: returns.text,
-    examples: codeToHtml([formattedSignature, ...examples].join('\n')),
+    signature: codeToHtml(formattedSignature),
+    examples: codeToHtml(examples.join('\n')),
     deprecated: mdToHtml(deprecated),
     seeAlsos: seeAlsos.map((seeAlso) => mdToHtml(seeAlso, true)),
   };