Skip to content

Added @returns to the documentation #61

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
peterpeterparker merged 1 commit into from
Jul 4, 2025
Merged

Added @returns to the documentation #61

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 19 additions & 1 deletion src/lib/markdown.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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[] =>
Expand Down Expand Up @@ -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);
Expand Down Expand Up @@ -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`
];
Expand All @@ -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);
Expand Down
2 changes: 1 addition & 1 deletion src/test/markdown.spec.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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: {
Expand Down
11 changes: 10 additions & 1 deletion src/test/mock.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -173,6 +173,15 @@
"kind": "link"
}
]
},
{
"name": "returns",
"text": [
{
"text": "The balance of the specified account identifier",
"kind": "text"
}
]
}
],
"doc_type": "function"
Expand Down Expand Up @@ -551,4 +560,4 @@
],
"fileName": "src/test/mock.ts"
}
]
]
43 changes: 23 additions & 20 deletions src/test/mock.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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

Expand All @@ -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

Expand All @@ -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

Expand All @@ -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

Expand All @@ -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

Expand All @@ -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

Expand All @@ -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

Expand All @@ -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

Expand All @@ -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

Expand All @@ -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

Expand Down Expand Up @@ -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

Expand All @@ -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)

1 change: 1 addition & 0 deletions src/test/mock.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
Loading