feat: render jsDocs and source url for classes and interfaces (#68)

* feat: render jsDocs for classes and interfaces

* 🤖 Documentation auto-update

* feat: print references in class

* feat: interfaces links and markdown

* test: see

---------

Co-authored-by: github-actions <41898282+github-actions[bot]@users.noreply.github.com>

Author: peterpeterparker

src/lib/parser/markdown.ts

@@ -7,7 +7,7 @@ import type {
   MarkdownOptions
 } from '../types';
 import {jsDocsMetadata, jsDocsToParams} from './jdocs/mapper';
-import {emojiTitle, metadataToMarkdown, sourceCodeLink} from './render';
+import {emojiTitle, metadataToMarkdown} from './render';
 import type {Params, Row} from './types';
 
 const toParams = (parameters?: DocEntry[]): Params[] =>
@@ -39,17 +39,21 @@ const classesToMarkdown = ({
   entry: DocEntry;
 } & Required<Pick<MarkdownOptions, 'headingLevel'>> &
   Omit<MarkdownOptions, 'headingLevel'>): string => {
-  const {name, url, documentation, methods, properties, constructors} = entry;
+  const {name, url, documentation, methods, properties, constructors, jsDocs} = entry;
 
   const markdown: string[] = [`${headingLevel}${emojiTitle({emoji, key: 'classes'})} ${name}\n`];
 
   if (documentation !== undefined && documentation !== '') {
     markdown.push(`${documentation}\n`);
   }
 
-  if (url !== undefined) {
-    markdown.push(sourceCodeLink({emoji, url}));
-  }
+  const metadata = metadataToMarkdown({
+    ...jsDocsMetadata(jsDocs),
+    url,
+    emoji
+  });
+
+  markdown.push(...metadata);
 
   const publicConstructors: DocEntryConstructor[] = (constructors ?? []).filter(
     ({visibility}) => visibility === 'public'
@@ -146,7 +150,7 @@ const interfacesToMarkdown = ({
 } & Required<Pick<MarkdownOptions, 'headingLevel'>> &
   Omit<MarkdownOptions, 'headingLevel'> &
   Pick<MarkdownOptions, 'emoji'>): string => {
-  const {name, documentation} = entry;
+  const {name, documentation, jsDocs, url} = entry;
 
   const markdown: string[] = [
     `${headingLevel}# ${emoji === undefined || emoji === null ? '' : ':gear: '}${name}\n`
@@ -156,6 +160,14 @@ const interfacesToMarkdown = ({
     markdown.push(`${documentation}\n`);
   }
 
+  const metadata = metadataToMarkdown({
+    ...jsDocsMetadata(jsDocs),
+    url,
+    emoji
+  });
+
+  markdown.push(...metadata);
+
   markdown.push(`| Property | Type | Description |`);
   markdown.push('| ---------- | ---------- | ---------- |');
 

src/lib/parser/render.ts

@@ -10,7 +10,7 @@ export const emojiTitle = ({
 } & Pick<MarkdownOptions, 'emoji'>): string =>
   emoji === undefined || emoji === null ? '' : ` :${emoji[key]}:`;
 
-export const sourceCodeLink = ({
+const sourceCodeLink = ({
   url,
   emoji
 }: Pick<MarkdownOptions, 'emoji'> & Required<Pick<DocEntry, 'url'>>): string =>

src/test/mock.json

@@ -426,6 +426,19 @@
             "kind": "text"
           }
         ]
+      },
+      {
+        "name": "see",
+        "text": [
+          {
+            "text": "https",
+            "kind": "text"
+          },
+          {
+            "text": "://github.com/peterpeterparker/tsdoc-markdown",
+            "kind": "text"
+          }
+        ]
       }
     ],
     "doc_type": "interface",

src/test/mock.md

@@ -95,7 +95,7 @@ function submit() {
 | ---------- | ---------- |
 | `MyObject.someFunction` | `() => void` |
 
-[:link: Source](https://github.com/peterpeterparker/tsdoc-markdown/tree/main/src/test/mock.ts#L282)
+[:link: Source](https://github.com/peterpeterparker/tsdoc-markdown/tree/main/src/test/mock.ts#L283)
 
 
 ## :wrench: Constants
@@ -133,7 +133,7 @@ console.log(result.success); // true or false
 ```
 
 
-[:link: Source](https://github.com/peterpeterparker/tsdoc-markdown/tree/main/src/test/mock.ts#L299)
+[:link: Source](https://github.com/peterpeterparker/tsdoc-markdown/tree/main/src/test/mock.ts#L300)
 
 ### :gear: SOMETHING
 
@@ -151,7 +151,7 @@ References:
 * [Source code](https://github.com/peterpeterparker/tsdoc-markdown)
 
 
-[:link: Source](https://github.com/peterpeterparker/tsdoc-markdown/tree/main/src/test/mock.ts#L339)
+[:link: Source](https://github.com/peterpeterparker/tsdoc-markdown/tree/main/src/test/mock.ts#L340)
 
 
 ## :factory: LedgerCanister
@@ -288,7 +288,12 @@ Description
 
 Should differentiate methods / properties and static methods / properties
 
-[:link: Source](https://github.com/peterpeterparker/tsdoc-markdown/tree/main/src/test/mock.ts#L317)
+References:
+
+* [https://github.com/peterpeterparker/tsdoc-markdown](https://github.com/peterpeterparker/tsdoc-markdown)
+
+
+[:link: Source](https://github.com/peterpeterparker/tsdoc-markdown/tree/main/src/test/mock.ts#L318)
 
 ### Static Methods
 
@@ -300,7 +305,7 @@ Should differentiate methods / properties and static methods / properties
 | ---------- | ---------- |
 | `add` | `(n1: Number, n2: Number) => Number` |
 
-[:link: Source](https://github.com/peterpeterparker/tsdoc-markdown/tree/main/src/test/mock.ts#L327)
+[:link: Source](https://github.com/peterpeterparker/tsdoc-markdown/tree/main/src/test/mock.ts#L328)
 
 ### Methods
 
@@ -312,7 +317,7 @@ Should differentiate methods / properties and static methods / properties
 | ---------- | ---------- |
 | `add` | `(n: Number) => Number` |
 
-[:link: Source](https://github.com/peterpeterparker/tsdoc-markdown/tree/main/src/test/mock.ts#L323)
+[:link: Source](https://github.com/peterpeterparker/tsdoc-markdown/tree/main/src/test/mock.ts#L324)
 
 ### Static Properties
 
@@ -324,7 +329,7 @@ Should differentiate methods / properties and static methods / properties
 | ---------- | ---------- |
 | `world` | `string` |
 
-[:link: Source](https://github.com/peterpeterparker/tsdoc-markdown/tree/main/src/test/mock.ts#L319)
+[:link: Source](https://github.com/peterpeterparker/tsdoc-markdown/tree/main/src/test/mock.ts#L320)
 
 ### Properties
 
@@ -336,7 +341,7 @@ Should differentiate methods / properties and static methods / properties
 | ---------- | ---------- |
 | `hello` | `string` |
 
-[:link: Source](https://github.com/peterpeterparker/tsdoc-markdown/tree/main/src/test/mock.ts#L318)
+[:link: Source](https://github.com/peterpeterparker/tsdoc-markdown/tree/main/src/test/mock.ts#L319)
 
 ## :nut_and_bolt: Enum
 
@@ -347,6 +352,8 @@ Should differentiate methods / properties and static methods / properties
 
 
 
+[:link: Source](https://github.com/peterpeterparker/tsdoc-markdown/tree/main/src/test/mock.ts#L183)
+
 | Property | Type | Description |
 | ---------- | ---------- | ---------- |
 | `SECOND` | `1000` |  |
@@ -357,6 +364,8 @@ Should differentiate methods / properties and static methods / properties
 
 
 
+[:link: Source](https://github.com/peterpeterparker/tsdoc-markdown/tree/main/src/test/mock.ts#L188)
+
 | Property | Type | Description |
 | ---------- | ---------- | ---------- |
 | `T1` | `` |  |
@@ -373,6 +382,8 @@ Should differentiate methods / properties and static methods / properties
 
 A Foo interface description.
 
+[:link: Source](https://github.com/peterpeterparker/tsdoc-markdown/tree/main/src/test/mock.ts#L157)
+
 | Property | Type | Description |
 | ---------- | ---------- | ---------- |
 | `hello` | `string` | Says hello. |
@@ -384,6 +395,13 @@ A Foo interface description.
 
 Use a URL redirect to prevent broken links if you've moved a page or to shorten URLs.
 
+References:
+
+* [https://github.com/peterpeterparker/tsdoc-markdown](https://github.com/peterpeterparker/tsdoc-markdown)
+
+
+[:link: Source](https://github.com/peterpeterparker/tsdoc-markdown/tree/main/src/test/mock.ts#L259)
+
 | Property | Type | Description |
 | ---------- | ---------- | ---------- |
 | `source` | `string` | The glob pattern or specific path to match for incoming requests that should be redirected. type: {StorageConfigSourceGlob} |
@@ -432,5 +450,5 @@ A type yolo
 | ---------- | ---------- |
 | `SatelliteConfig` | `Either<SatelliteId, SatelliteIds> and CliConfig and SatelliteConfigOptions` |
 
-[:link: Source](https://github.com/peterpeterparker/tsdoc-markdown/tree/main/src/test/mock.ts#L278)
+[:link: Source](https://github.com/peterpeterparker/tsdoc-markdown/tree/main/src/test/mock.ts#L279)
 

src/test/mock.ts

@@ -254,6 +254,7 @@ export type StorageConfigSourceGlob = string;
 /**
  * Use a URL redirect to prevent broken links if you've moved a page or to shorten URLs.
  * @interface StorageConfigRedirect
+ * @see https://github.com/peterpeterparker/tsdoc-markdown
  */
 export interface StorageConfigRedirect {
   /**