added the returns annotation to the generated documentation (#61)

fixes: #60

Signed-off-by: Erik Jan de Wit <[email protected]>

Author: edewit

src/lib/markdown.ts

@@ -16,6 +16,7 @@ type Row = Required<Pick<DocEntry, 'name' | 'type' | 'documentation'>> &
   Pick<DocEntry, 'url'> & {
     params: Params[];
     examples: string[];
+    returnType?: string;
   };
 
 const toParams = (parameters?: DocEntry[]): Params[] =>
@@ -208,6 +209,19 @@ const toMarkdown = ({
   headingLevel: MarkdownHeadingLevel | '####';
   docType: 'Constant' | 'Function' | 'Method' | 'Property' | 'Type' | 'Enum';
 } & Pick<MarkdownOptions, 'emoji'>): string => {
+  const jsDocsToReturnType = (jsDocs: JSDocTagInfo[]): string => {
+    const returns: JSDocTagInfo[] = jsDocs.filter(({name}: JSDocTagInfo) => name === 'returns');
+    const texts: Array<SymbolDisplayPart[] | undefined> = returns.map(({text}) => text);
+    const returnType = texts.reduce((acc: SymbolDisplayPart[][], values: SymbolDisplayPart[] | undefined) => {
+      if (values === undefined) {
+        return acc;
+      }
+
+      return [...acc, values];
+    }, []);
+
+    return returnType.map((parts) => parts.map(({text}) => text).join('')).join(' ');
+  };
   const jsDocsToParams = (jsDocs: JSDocTagInfo[]): Params[] => {
     const params: JSDocTagInfo[] = jsDocs.filter(({name}: JSDocTagInfo) => name === 'param');
     const texts: Array<SymbolDisplayPart[] | undefined> = params.map(({text}) => text);
@@ -251,12 +265,13 @@ const toMarkdown = ({
       type: type ?? '',
       documentation: documentation ?? '',
       params: [...toParams(parameters), ...jsDocsToParams(jsDocs ?? [])],
+      returnType: jsDocsToReturnType(jsDocs ?? []),
       examples: [...jsDocsToExamples(jsDocs ?? [])],
       url
     })
   );
 
-  const rowToMarkdown = ({name, documentation, type, params, examples, url}: Row): string => {
+  const rowToMarkdown = ({name, documentation, type, params, returnType, examples, url}: Row): string => {
     const markdown: string[] = [
       `${headingLevel}# ${emoji === undefined || emoji === null ? '' : ':gear: '}${name}\n`
     ];
@@ -276,6 +291,9 @@ const toMarkdown = ({
       markdown.push(...inlineParams(params));
       markdown.push('\n');
     }
+    if (returnType) {
+      markdown.push(`Returns:\n\t${returnType}\n`);
+    }
     if (examples.length) {
       markdown.push('Examples:\n');
       markdown.push(...examples);

src/test/markdown.spec.ts

@@ -21,7 +21,7 @@ describe('markdown', () => {
     expect(markdown).toEqual(expectedDoc);
   });
 
-  it.each([35, 118, 146])('should generate a markdown link to line %s', (line) => {
+  it.each([35, 119, 147])('should generate a markdown link to line %s', (line) => {
     const doc = buildDocumentation({
       inputFiles: ['./src/test/mock.ts'],
       options: {

src/test/mock.json

@@ -173,6 +173,15 @@
                 "kind": "link"
               }
             ]
+          },
+          {
+            "name": "returns",
+            "text": [
+              {
+                "text": "The balance of the specified account identifier",
+                "kind": "text"
+              }
+            ]
           }
         ],
         "doc_type": "function"
@@ -551,4 +560,4 @@
     ],
     "fileName": "src/test/mock.ts"
   }
-]
+]

src/test/mock.md

@@ -87,15 +87,15 @@ function submit() {
 ```
 
 
-[:link: Source](https://github.com/peterpeterparker/tsdoc-markdown/tree/main/src/test/mock.ts#L238)
+[:link: Source](https://github.com/peterpeterparker/tsdoc-markdown/tree/main/src/test/mock.ts#L239)
 
 ### :gear: MyObject.someFunction
 
 | Function | Type |
 | ---------- | ---------- |
 | `MyObject.someFunction` | `() => void` |
 
-[:link: Source](https://github.com/peterpeterparker/tsdoc-markdown/tree/main/src/test/mock.ts#L281)
+[:link: Source](https://github.com/peterpeterparker/tsdoc-markdown/tree/main/src/test/mock.ts#L282)
 
 
 ## :wrench: Constants
@@ -132,7 +132,7 @@ console.log(result.success); // true or false
 ```
 
 
-[:link: Source](https://github.com/peterpeterparker/tsdoc-markdown/tree/main/src/test/mock.ts#L298)
+[:link: Source](https://github.com/peterpeterparker/tsdoc-markdown/tree/main/src/test/mock.ts#L299)
 
 
 ## :factory: LedgerCanister
@@ -179,7 +179,10 @@ Returns the balance of the specified account identifier.
 | ---------- | ---------- |
 | `accountBalance` | `({ certified }: { certified?: boolean or undefined; }) => Promise<{ icp: bigint; }>` |
 
-[:link: Source](https://github.com/peterpeterparker/tsdoc-markdown/tree/main/src/test/mock.ts#L69)
+Returns:
+	The balance of the specified account identifier
+
+[:link: Source](https://github.com/peterpeterparker/tsdoc-markdown/tree/main/src/test/mock.ts#L70)
 
 #### :gear: shouldBeDocumented
 
@@ -189,7 +192,7 @@ Public method.
 | ---------- | ---------- |
 | `shouldBeDocumented` | `() => void` |
 
-[:link: Source](https://github.com/peterpeterparker/tsdoc-markdown/tree/main/src/test/mock.ts#L97)
+[:link: Source](https://github.com/peterpeterparker/tsdoc-markdown/tree/main/src/test/mock.ts#L98)
 
 ### Properties
 
@@ -203,11 +206,11 @@ The documentation of the public property.
 | ---------- | ---------- |
 | `publicShouldBeDocumented` | `string` |
 
-[:link: Source](https://github.com/peterpeterparker/tsdoc-markdown/tree/main/src/test/mock.ts#L80)
+[:link: Source](https://github.com/peterpeterparker/tsdoc-markdown/tree/main/src/test/mock.ts#L81)
 
 ## :factory: SnsLedgerCanister
 
-[:link: Source](https://github.com/peterpeterparker/tsdoc-markdown/tree/main/src/test/mock.ts#L118)
+[:link: Source](https://github.com/peterpeterparker/tsdoc-markdown/tree/main/src/test/mock.ts#L119)
 
 ### Constructors
 
@@ -227,7 +230,7 @@ This create function is public as well.
 | ---------- | ---------- |
 | `create` | `(options: { canisterId?: string or undefined; }) => SnsLedgerCanister` |
 
-[:link: Source](https://github.com/peterpeterparker/tsdoc-markdown/tree/main/src/test/mock.ts#L133)
+[:link: Source](https://github.com/peterpeterparker/tsdoc-markdown/tree/main/src/test/mock.ts#L134)
 
 ### Methods
 
@@ -241,11 +244,11 @@ The token metadata (name, symbol, etc.).
 | ---------- | ---------- |
 | `metadata` | `(params: QueryParams) => Promise<SnsTokenMetadataResponse>` |
 
-[:link: Source](https://github.com/peterpeterparker/tsdoc-markdown/tree/main/src/test/mock.ts#L142)
+[:link: Source](https://github.com/peterpeterparker/tsdoc-markdown/tree/main/src/test/mock.ts#L143)
 
 ## :factory: default
 
-[:link: Source](https://github.com/peterpeterparker/tsdoc-markdown/tree/main/src/test/mock.ts#L146)
+[:link: Source](https://github.com/peterpeterparker/tsdoc-markdown/tree/main/src/test/mock.ts#L147)
 
 ### Methods
 
@@ -259,13 +262,13 @@ Description
 | ---------- | ---------- |
 | `bar` | `() => void` |
 
-[:link: Source](https://github.com/peterpeterparker/tsdoc-markdown/tree/main/src/test/mock.ts#L150)
+[:link: Source](https://github.com/peterpeterparker/tsdoc-markdown/tree/main/src/test/mock.ts#L151)
 
 ## :factory: Number
 
 Should differentiate methods / properties and static methods / properties
 
-[:link: Source](https://github.com/peterpeterparker/tsdoc-markdown/tree/main/src/test/mock.ts#L315)
+[:link: Source](https://github.com/peterpeterparker/tsdoc-markdown/tree/main/src/test/mock.ts#L316)
 
 ### Static Methods
 
@@ -277,7 +280,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#L325)
+[:link: Source](https://github.com/peterpeterparker/tsdoc-markdown/tree/main/src/test/mock.ts#L326)
 
 ### Methods
 
@@ -289,7 +292,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#L321)
+[:link: Source](https://github.com/peterpeterparker/tsdoc-markdown/tree/main/src/test/mock.ts#L322)
 
 ### Static Properties
 
@@ -301,7 +304,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#L317)
+[:link: Source](https://github.com/peterpeterparker/tsdoc-markdown/tree/main/src/test/mock.ts#L318)
 
 ### Properties
 
@@ -313,7 +316,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#L316)
+[:link: Source](https://github.com/peterpeterparker/tsdoc-markdown/tree/main/src/test/mock.ts#L317)
 
 ## :nut_and_bolt: Enum
 
@@ -383,7 +386,7 @@ A type yolo
 | ---------- | ---------- |
 | `yolo` | `'string'` |
 
-[:link: Source](https://github.com/peterpeterparker/tsdoc-markdown/tree/main/src/test/mock.ts#L175)
+[:link: Source](https://github.com/peterpeterparker/tsdoc-markdown/tree/main/src/test/mock.ts#L176)
 
 ### :gear: Abc
 
@@ -393,21 +396,21 @@ A type yolo
 | ---------- | ---------- |
 | `Abc` | `Foo and {hello: string}` |
 
-[:link: Source](https://github.com/peterpeterparker/tsdoc-markdown/tree/main/src/test/mock.ts#L180)
+[:link: Source](https://github.com/peterpeterparker/tsdoc-markdown/tree/main/src/test/mock.ts#L181)
 
 ### :gear: StorageConfigSourceGlob
 
 | Type | Type |
 | ---------- | ---------- |
 | `StorageConfigSourceGlob` |  |
 
-[:link: Source](https://github.com/peterpeterparker/tsdoc-markdown/tree/main/src/test/mock.ts#L251)
+[:link: Source](https://github.com/peterpeterparker/tsdoc-markdown/tree/main/src/test/mock.ts#L252)
 
 ### :gear: SatelliteConfig
 
 | Type | Type |
 | ---------- | ---------- |
 | `SatelliteConfig` | `Either<SatelliteId, SatelliteIds> and CliConfig and SatelliteConfigOptions` |
 
-[:link: Source](https://github.com/peterpeterparker/tsdoc-markdown/tree/main/src/test/mock.ts#L277)
+[:link: Source](https://github.com/peterpeterparker/tsdoc-markdown/tree/main/src/test/mock.ts#L278)
 

src/test/mock.ts

@@ -65,6 +65,7 @@ export class LedgerCanister {
    * @param params.certified Update calls?
    *
    * @throws an {@link Error}
+   * @returns {Promise<{icp: bigint}>} The balance of the specified account identifier
    */
   public accountBalance = async ({
     certified = true