@ng-prism/plugin-jsdoc 22.3.0 → 22.4.0

package/README.md

@@ -2,7 +2,7 @@
 
 API documentation plugin for [@ng-prism/core](https://github.com/dyingangel666/ng-prism). Extracts JSDoc comments from component source code at build time and renders an interactive API panel.
 
-> **Full documentation:** [ng-prism Docs — JSDoc Plugin](https://dyingangel666.github.io/ng-prism/#/plugins/jsdoc)
+> **Full documentation:** [ng-prism Docs: JSDoc Plugin](https://dyingangel666.github.io/ng-prism/#/plugins/jsdoc)
 
 ## Installation
 
@@ -49,11 +49,11 @@ JSDoc descriptions are rendered as Markdown:
 - Headings (`#`, `##`, `###`)
 - Lists (ordered/unordered) and inline code (`` `code` ``)
 - Bold (`**text**`), italic (`*text*`), and links (`[text](url)`)
-- Fenced code blocks with a language hint (` ```html `, ` ```scss ` …)
+- Fenced code blocks with a language hint (` ```html `, ` ```scss `, ...)
 
 Class descriptions are rendered as block Markdown; input/output/method descriptions are
 rendered inline (no wrapping `<p>`). Existing plain-text descriptions keep working
-unchanged — plain text is valid Markdown.
+unchanged, since plain text is valid Markdown.
 
 ````typescript
 /**
@@ -61,8 +61,8 @@ unchanged — plain text is valid Markdown.
  *
  * ## Size
  *
- * - `small` (4px) — inline indicators
- * - `large` (9px, default) — section-level loading
+ * - `small` (4px): inline indicators
+ * - `large` (9px, default): section-level loading
  *
  * @example
  * ```html
@@ -72,9 +72,9 @@ unchanged — plain text is valid Markdown.
 ````
 
 `@example` blocks accept a fenced code block with a language hint. The language is
-passed through to `ngx-highlightjs` (`html`, `scss`, `typescript`, …). Examples without
+passed through to `ngx-highlightjs` (`html`, `scss`, `typescript`, ...). Examples without
 fences fall back to `typescript` for backwards compatibility. Make sure the languages
-you reference are registered with `highlight.js` in your app — `highlight.js`'s core
+you reference are registered with `highlight.js` in your app. `highlight.js`'s core
 language set is loaded by default, but additional languages must be registered
 explicitly by the consumer.
 

package/dist/jsdoc-extractor.d.ts

@@ -1,3 +1,11 @@
 import type { JsDocData } from './jsdoc.types.js';
-export declare function extractJsDocData(filePath: string, className: string): JsDocData | null;
+/**
+ * `baseClasses` come from the scanner, nearest first. Members are read from
+ * the class and then from each of them; the first class that declares a
+ * member decides its tags, as a redeclaration replaces the inherited one.
+ */
+export declare function extractJsDocData(filePath: string, className: string, baseClasses?: {
+    className: string;
+    filePath: string;
+}[]): JsDocData | null;
 //# sourceMappingURL=jsdoc-extractor.d.ts.map

package/dist/jsdoc-extractor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"jsdoc-extractor.d.ts","sourceRoot":"","sources":["../src/jsdoc-extractor.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,SAAS,EAAkC,MAAM,kBAAkB,CAAC;AAElF,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CActF"}
+{"version":3,"file":"jsdoc-extractor.d.ts","sourceRoot":"","sources":["../src/jsdoc-extractor.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,SAAS,EAAkC,MAAM,kBAAkB,CAAC;AAElF;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,WAAW,GAAE;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,EAAO,GAAG,SAAS,GAAG,IAAI,CAyBnJ"}

package/dist/jsdoc-extractor.js

@@ -1,16 +1,29 @@
 import { readFileSync } from 'node:fs';
 import ts from 'typescript';
-export function extractJsDocData(filePath, className) {
-    const sourceText = readFileSync(filePath, 'utf-8');
-    const sourceFile = ts.createSourceFile(filePath, sourceText, ts.ScriptTarget.ES2022, true);
-    const classDecl = findClassByName(sourceFile, className);
+/**
+ * `baseClasses` come from the scanner, nearest first. Members are read from
+ * the class and then from each of them; the first class that declares a
+ * member decides its tags, as a redeclaration replaces the inherited one.
+ */
+export function extractJsDocData(filePath, className, baseClasses = []) {
+    const sourceFiles = new Map();
+    const findClass = (path, name) => {
+        let sourceFile = sourceFiles.get(path);
+        if (!sourceFile) {
+            sourceFile = ts.createSourceFile(path, readFileSync(path, 'utf-8'), ts.ScriptTarget.ES2022, true);
+            sourceFiles.set(path, sourceFile);
+        }
+        return findClassByName(sourceFile, name);
+    };
+    const classDecl = findClass(filePath, className);
     if (!classDecl)
         return null;
+    const hierarchy = [classDecl, ...baseClasses.flatMap((base) => findClass(base.filePath, base.className) ?? [])];
     return {
         classDescription: extractDescription(classDecl),
         classTags: extractTags(classDecl),
-        memberTags: extractAllMemberTags(classDecl),
-        methods: extractPublicMethods(classDecl)
+        memberTags: extractAllMemberTags(hierarchy),
+        methods: extractPublicMethods(hierarchy)
     };
 }
 function findClassByName(sourceFile, className) {
@@ -90,18 +103,37 @@ function tagCommentToString(comment) {
         .join('')
         .trim() || undefined);
 }
-function extractAllMemberTags(classDecl) {
+function extractAllMemberTags(hierarchy) {
     const result = {};
+    const shadowed = new Set();
+    for (const classDecl of hierarchy) {
+        for (const member of classDecl.members) {
+            const name = getMemberName(member);
+            if (!name || shadowed.has(name))
+                continue;
+            const tags = ts.getJSDocTags(member);
+            if (tags.length === 0)
+                continue;
+            result[name] = buildTagsFromList(tags);
+        }
+        addMemberNames(classDecl, shadowed);
+    }
+    return result;
+}
+/**
+ * A member with JSDoc of its own hides the same name further up, as it does
+ * for TypeScript and for the description the scanner reads; one without
+ * keeps the documentation it inherits. Applied after the whole class, so the
+ * getter, setter or overloads next to a member are read too. A static member
+ * hides nothing, since inputs, outputs and methods are instance members.
+ */
+function addMemberNames(classDecl, names) {
     for (const member of classDecl.members) {
         const name = getMemberName(member);
-        if (!name)
-            continue;
-        const tags = ts.getJSDocTags(member);
-        if (tags.length === 0)
-            continue;
-        result[name] = buildTagsFromList(tags);
+        const isStatic = ts.canHaveModifiers(member) && ts.getModifiers(member)?.some((m) => m.kind === ts.SyntaxKind.StaticKeyword);
+        if (name && !isStatic && ts.getJSDocCommentsAndTags(member).length > 0)
+            names.add(name);
     }
-    return result;
 }
 function getMemberName(member) {
     if (!member.name)
@@ -122,29 +154,35 @@ const LIFECYCLE_HOOKS = new Set([
     'ngAfterViewInit',
     'ngAfterViewChecked'
 ]);
-function extractPublicMethods(classDecl) {
+function extractPublicMethods(hierarchy) {
     const result = [];
-    const sourceFile = classDecl.getSourceFile();
-    for (const member of classDecl.members) {
-        if (!ts.isMethodDeclaration(member))
-            continue;
-        const name = getMemberName(member);
-        if (!name || name.startsWith('_'))
-            continue;
-        if (LIFECYCLE_HOOKS.has(name))
-            continue;
-        const isPrivate = member.modifiers?.some((m) => m.kind === ts.SyntaxKind.PrivateKeyword || m.kind === ts.SyntaxKind.ProtectedKeyword);
-        if (isPrivate)
-            continue;
-        if (!hasDirectJsDoc(member, sourceFile))
-            continue;
-        const description = extractDescription(member);
-        const tags = extractTags(member);
-        const params = extractParamDocs(member);
-        const returnType = member.type ? member.type.getText() : undefined;
-        if (!description && Object.keys(tags).length === 0)
-            continue;
-        result.push({ name, description, tags, params, returnType });
+    const shadowed = new Set();
+    for (const classDecl of hierarchy) {
+        const sourceFile = classDecl.getSourceFile();
+        for (const member of classDecl.members) {
+            if (!ts.isMethodDeclaration(member))
+                continue;
+            const name = getMemberName(member);
+            if (!name || shadowed.has(name))
+                continue;
+            if (name.startsWith('_'))
+                continue;
+            if (LIFECYCLE_HOOKS.has(name))
+                continue;
+            const isPrivate = member.modifiers?.some((m) => m.kind === ts.SyntaxKind.PrivateKeyword || m.kind === ts.SyntaxKind.ProtectedKeyword);
+            if (isPrivate)
+                continue;
+            if (!hasDirectJsDoc(member, sourceFile))
+                continue;
+            const description = extractDescription(member);
+            const tags = extractTags(member);
+            const params = extractParamDocs(member);
+            const returnType = member.type ? member.type.getText() : undefined;
+            if (!description && Object.keys(tags).length === 0)
+                continue;
+            result.push({ name, description, tags, params, returnType });
+        }
+        addMemberNames(classDecl, shadowed);
     }
     return result;
 }

package/dist/jsdoc-panel.component.js

@@ -427,7 +427,7 @@ export class JsDocPanelComponent {
     classDescription = computed(() => this.jsdocData()?.classDescription, /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "classDescription" }] : /* istanbul ignore next */ []));
     // Source is component-author JSDoc compiled into the manifest at build time,
-    // not user input — bypassing sanitization is safe here.
+    // not user input, so bypassing sanitization is safe here.
     renderedClassDescription = computed(() => {
         const html = renderBlockMarkdown(this.classDescription());
         return html ? this.sanitizer.bypassSecurityTrustHtml(html) : null;

package/dist/jsdoc-plugin.js

@@ -3,7 +3,7 @@ export function jsDocPlugin() {
     return {
         name: '@ng-prism/plugin-jsdoc',
         async onComponentScanned(component) {
-            const jsdoc = extractJsDocData(component.filePath, component.className);
+            const jsdoc = extractJsDocData(component.filePath, component.className, component.baseClasses);
             if (!jsdoc)
                 return;
             return {

package/dist/schematics/ng-add/index.js

@@ -12,10 +12,10 @@ function injectPlugin(options) {
             call: PLUGIN_CALL
         });
         if (changed) {
-            context.logger.info(`  ${PLUGIN_IMPORT_FROM} → added to ${configPath}`);
+            context.logger.info(`  ${PLUGIN_IMPORT_FROM} added to ${configPath}`);
         }
         else {
-            context.logger.info(`  ${PLUGIN_IMPORT_FROM} already configured — skipped`);
+            context.logger.info(`  ${PLUGIN_IMPORT_FROM} already configured, skipped`);
         }
         return tree;
     };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ng-prism/plugin-jsdoc",
-  "version": "22.3.0",
+  "version": "22.4.0",
   "description": "JSDoc API documentation panel for ng-prism.",
   "ng-add": {
     "save": "devDependencies"
@@ -36,7 +36,7 @@
   ],
   "peerDependencies": {
     "@angular/core": ">=20.0.0",
-    "@ng-prism/core": "^22.3.0-0",
+    "@ng-prism/core": "^22.4.0-0",
     "highlight.js": ">=11.0.0",
     "ngx-highlightjs": ">=14.0.0",
     "typescript": ">=5.5.0",