Skip to content

Commit 1a008ce

Browse files
pgonzalpgonzal
committed
Function parameters and return value are now documented
1 parent 541b5fb commit 1a008ce

File tree

8 files changed

+111
-26
lines changed

8 files changed

+111
-26
lines changed

‎apps/api-documenter/src/markdown/MarkdownDocumenter.ts‎

Lines changed: 68 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,6 @@
11
// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
22
// See LICENSE in the project root for license information.
33

4-
import * as colors from 'colors';
54
import * as path from 'path';
65

76
import {
@@ -13,7 +12,6 @@ import {
1312
DocSection,
1413
DocPlainText,
1514
DocLinkTag,
16-
DocNode,
1715
TSDocConfiguration,
1816
StringBuilder,
1917
DocNodeKind,
@@ -34,7 +32,8 @@ import {
3432
ApiDeclarationMixin,
3533
ApiStaticMixin,
3634
ApiResultTypeMixin,
37-
ApiPropertyItem
35+
ApiPropertyItem,
36+
ApiFunctionLikeMixin
3837
} from '@microsoft/api-extractor';
3938

4039
import { MarkdownRenderer } from '../utils/MarkdownRenderer';
@@ -141,6 +140,7 @@ export class MarkdownDocumenter {
141140
break;
142141
case ApiItemKind.Method:
143142
case ApiItemKind.MethodSignature:
143+
this._writeFunctionLikeTables(output, apiItem as ApiFunctionLikeMixin);
144144
break;
145145
case ApiItemKind.Namespace:
146146
break;
@@ -411,6 +411,71 @@ export class MarkdownDocumenter {
411411
}
412412
}
413413

414+
/**
415+
* GENERATE PAGE: FUNCTION-LIKE
416+
*/
417+
private _writeFunctionLikeTables(output: DocSection, apiFunctionLike: ApiFunctionLikeMixin): void {
418+
const configuration: TSDocConfiguration = this._tsdocConfiguration;
419+
420+
if (apiFunctionLike.name === 'example') {
421+
debugger;
422+
}
423+
424+
const parametersTable: DocTable = new DocTable({ configuration,
425+
headerTitles: [ 'Parameter', 'Type', 'Description' ]
426+
});
427+
428+
for (const apiParameter of apiFunctionLike.parameters) {
429+
const parameterDescription: DocSection = new DocSection({ configuration } );
430+
if (apiParameter.tsdocParamBlock) {
431+
this._appendSection(parameterDescription, apiParameter.tsdocParamBlock.content);
432+
}
433+
434+
parametersTable.addRow(
435+
new DocTableRow({ configuration }, [
436+
this._createTitleCell(apiParameter),
437+
new DocTableCell({configuration}, [
438+
new DocParagraph({ configuration }, [
439+
new DocCodeSpan({ configuration, code: apiParameter.resultTypeSignature })
440+
])
441+
]),
442+
new DocTableCell({configuration}, parameterDescription.nodes)
443+
])
444+
);
445+
}
446+
447+
if (parametersTable.rows.length > 0) {
448+
output.appendNode(new DocHeading({ configuration: this._tsdocConfiguration, title: 'Parameters' }));
449+
output.appendNode(parametersTable);
450+
}
451+
452+
if (ApiResultTypeMixin.isBaseClassOf(apiFunctionLike)) {
453+
454+
output.appendNode(
455+
new DocParagraph({ configuration }, [
456+
new DocEmphasisSpan({ configuration, bold: true}, [
457+
new DocPlainText({ configuration, text: 'Returns:' })
458+
])
459+
])
460+
);
461+
462+
output.appendNode(
463+
new DocParagraph({ configuration }, [
464+
new DocCodeSpan({ configuration, code: apiFunctionLike.resultTypeSignature })
465+
])
466+
);
467+
468+
if (apiFunctionLike instanceof ApiDocumentedItem) {
469+
if (apiFunctionLike.tsdocComment) {
470+
if (apiFunctionLike.tsdocComment.returnsBlock) {
471+
this._appendSection(output, apiFunctionLike.tsdocComment.returnsBlock.content);
472+
}
473+
}
474+
}
475+
476+
}
477+
}
478+
414479
private _createTitleCell(apiItem: ApiItem): DocTableCell {
415480
const configuration: TSDocConfiguration = this._tsdocConfiguration;
416481

‎apps/api-documenter/src/nodes/CustomDocNodeKind.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
import { TSDocConfiguration, DocNode, DocNodeKind } from '@microsoft/tsdoc';
1+
import { TSDocConfiguration, DocNodeKind } from '@microsoft/tsdoc';
22
import { DocEmphasisSpan } from './DocEmphasisSpan';
33
import { DocHeading } from './DocHeading';
44
import { DocNoteBox } from './DocNoteBox';

‎apps/api-documenter/src/nodes/DocTable.ts‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,8 +3,7 @@
33

44
import {
55
IDocNodeParameters,
6-
DocNode,
7-
DocSection
6+
DocNode
87
} from '@microsoft/tsdoc';
98
import { CustomDocNodeKind } from './CustomDocNodeKind';
109
import { DocTableRow } from './DocTableRow';

‎apps/api-documenter/src/nodes/DocTableRow.ts‎

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4,12 +4,10 @@
44
import {
55
IDocNodeParameters,
66
DocNode,
7-
DocSection,
87
DocPlainText
98
} from '@microsoft/tsdoc';
109
import { CustomDocNodeKind } from './CustomDocNodeKind';
1110
import { DocTableCell } from './DocTableCell';
12-
import { DocTable } from './DocTable';
1311

1412
/**
1513
* Constructor parameters for {@link DocTableRow}.

‎apps/api-extractor/src/api/mixins/ApiFunctionLikeMixin.ts‎

Lines changed: 15 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
22
// See LICENSE in the project root for license information.s
33

4-
import { ApiItem, IApiItemJson, IApiItemConstructor, IApiItemOptions } from '../model/ApiItem';
4+
import { ApiItem, ApiItem_parent, IApiItemJson, IApiItemConstructor, IApiItemOptions } from '../model/ApiItem';
55
import { ApiParameter } from '../model/ApiParameter';
66

77
/** @public */
@@ -56,7 +56,13 @@ export function ApiFunctionLikeMixin<TBaseClass extends IApiItemConstructor>(bas
5656
const options: IApiFunctionLikeMixinOptions = args[0];
5757
this[_overloadIndex] = options.overloadIndex;
5858

59-
this[_parameters] = options.parameters || [];
59+
this[_parameters] = [];
60+
61+
if (options.parameters) {
62+
for (const parameter of options.parameters) {
63+
this.addParameter(parameter);
64+
}
65+
}
6066
}
6167

6268
public get overloadIndex(): number {
@@ -68,7 +74,14 @@ export function ApiFunctionLikeMixin<TBaseClass extends IApiItemConstructor>(bas
6874
}
6975

7076
public addParameter(parameter: ApiParameter): void {
77+
const existingParent: ApiItem | undefined = parameter[ApiItem_parent];
78+
if (existingParent !== undefined) {
79+
throw new Error(`This ApiParameter has already been added to another function: "${existingParent.name}"`);
80+
}
81+
7182
this[_parameters].push(parameter);
83+
84+
parameter[ApiItem_parent] = this;
7285
}
7386

7487
/** @override */

‎apps/api-extractor/src/api/model/ApiItem.ts‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -79,8 +79,9 @@ export class ApiItem {
7979
}
8080

8181
/**
82-
* If this item was added to a ApiItemContainerMixin item, then this returns the parent item.
83-
* Otherwise it returns undefined.
82+
* If this item was added to a ApiItemContainerMixin item, then this returns the container item.
83+
* If this is an ApiParameter that was added to a method or function, then this returns the function item.
84+
* Otherwise, it returns undefined.
8485
* @virtual
8586
*/
8687
public get parent(): ApiItem | undefined {

‎apps/api-extractor/src/api/model/ApiParameter.ts‎

Lines changed: 7 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -3,16 +3,20 @@
33

44
import * as tsdoc from '@microsoft/tsdoc';
55

6-
import { ApiItemKind, ApiItem } from './ApiItem';
6+
import { ApiItemKind, ApiItem, IApiItemOptions } from './ApiItem';
77
import { IApiDeclarationMixinOptions, ApiDeclarationMixin } from '../mixins/ApiDeclarationMixin';
88
import { ApiDocumentedItem } from './ApiDocumentedItem';
9+
import { ApiResultTypeMixin, IApiResultTypeMixinOptions } from '../mixins/ApiResultTypeMixin';
910

1011
/** @public */
11-
export interface IApiParameterOptions extends IApiDeclarationMixinOptions {
12+
export interface IApiParameterOptions extends
13+
IApiDeclarationMixinOptions,
14+
IApiResultTypeMixinOptions,
15+
IApiItemOptions {
1216
}
1317

1418
/** @public */
15-
export class ApiParameter extends ApiDeclarationMixin(ApiItem) {
19+
export class ApiParameter extends ApiDeclarationMixin(ApiResultTypeMixin(ApiItem)) {
1620
public constructor(options: IApiParameterOptions) {
1721
super(options);
1822
}

‎apps/api-extractor/src/generators/ModelBuilder.ts‎

Lines changed: 16 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,7 @@ import { ReleaseTag } from '../aedoc/ReleaseTag';
2626
import { ApiReleaseTagMixin } from '../api/mixins/ApiReleaseTagMixin';
2727
import { ApiProperty } from '../api/model/ApiProperty';
2828
import { ApiMethodSignature } from '../api/model/ApiMethodSignature';
29+
import { ApiFunctionLikeMixin } from '../api/mixins/ApiFunctionLikeMixin';
2930

3031
export class ModelBuilder {
3132
private readonly _context: ExtractorContext;
@@ -203,12 +204,7 @@ export class ModelBuilder {
203204
overloadIndex });
204205

205206
for (const parameter of methodDeclaration.parameters) {
206-
const parameterSignature: string = parameter.getText().trim();
207-
208-
apiMethod.addParameter(new ApiParameter({
209-
name: parameter.name.getText() || '',
210-
signature: parameterSignature
211-
}));
207+
this._processApiParameter(parameter, apiMethod);
212208
}
213209

214210
parentApiItem.addMember(apiMethod);
@@ -238,18 +234,27 @@ export class ModelBuilder {
238234
overloadIndex });
239235

240236
for (const parameter of methodSignature.parameters) {
241-
const parameterSignature: string = parameter.getText().trim();
237+
this._processApiParameter(parameter, apiMethodSignature);
242238

243-
apiMethodSignature.addParameter(new ApiParameter({
244-
name: parameter.name.getText() || '',
245-
signature: parameterSignature
246-
}));
247239
}
248240

249241
parentApiItem.addMember(apiMethodSignature);
250242
}
251243
}
252244

245+
private _processApiParameter(parameterDeclaration: ts.ParameterDeclaration,
246+
functionLikeItem: ApiFunctionLikeMixin): void {
247+
248+
const signature: string = parameterDeclaration.getText().trim();
249+
const resultTypeSignature: string = this._getSignatureForTypeNode(parameterDeclaration.type);
250+
251+
functionLikeItem.addParameter(new ApiParameter({
252+
name: parameterDeclaration.name.getText() || '',
253+
signature,
254+
resultTypeSignature
255+
}));
256+
}
257+
253258
private _processApiNamespace(astDeclaration: AstDeclaration, exportedName: string | undefined,
254259
parentApiItem: ApiItemContainerMixin): void {
255260

0 commit comments

Comments
 (0)