Skip to content

Commit 911a017

Browse files
pgonzalpgonzal
committed
Update MarkdownRenderer.ts to build again
1 parent c19f4c0 commit 911a017

File tree

4 files changed

+13
-216
lines changed

4 files changed

+13
-216
lines changed

‎apps/api-documenter/src/utils/MarkdownRenderer.ts‎

Lines changed: 5 additions & 54 deletions
Original file line numberDiff line numberDiff line change
@@ -3,9 +3,8 @@
33

44
import {
55
IMarkupText,
6-
MarkupElement,
7-
IApiItemReference
8-
} from '@microsoft/api-extractor';
6+
MarkupElement
7+
} from './MarkupElement';
98

109
/**
1110
* Helper class used by MarkdownPageRenderer
@@ -56,49 +55,22 @@ class SimpleWriter {
5655
interface IRenderContext {
5756
writer: SimpleWriter;
5857
insideTable: boolean;
59-
options: IMarkdownRendererOptions;
6058
depth: number;
6159
}
6260

63-
export interface IMarkdownRenderApiLinkArgs {
64-
/**
65-
* The IApiItemReference being rendered.
66-
*/
67-
readonly reference: IApiItemReference;
68-
/**
69-
* The callback can assign text here that will be inserted before the link text.
70-
* Example: "["
71-
*/
72-
prefix: string;
73-
74-
/**
75-
* The callback can assign text here that will be inserted after the link text.
76-
* Example: "](./TargetPage.md)"
77-
*/
78-
suffix: string;
79-
}
80-
81-
export interface IMarkdownRendererOptions {
82-
/**
83-
* This callback receives an IMarkupApiLink, and returns the rendered markdown content.
84-
* If the callback is not provided, an error occurs if an IMarkupApiLink is encountered.
85-
*/
86-
onRenderApiLink?: (args: IMarkdownRenderApiLinkArgs) => void;
87-
}
8861

8962
/**
9063
* Renders MarkupElement content in the Markdown file format.
9164
* For more info: https://en.wikipedia.org/wiki/Markdown
9265
*/
9366
export class MarkdownRenderer {
9467

95-
public static renderElements(elements: MarkupElement[], options: IMarkdownRendererOptions): string {
68+
public static renderElements(elements: MarkupElement[]): string {
9669
const writer: SimpleWriter = new SimpleWriter();
9770

9871
const context: IRenderContext = {
9972
writer: writer,
10073
insideTable: false,
101-
options: options,
10274
depth: 0
10375
};
10476

@@ -243,30 +215,9 @@ export class MarkdownRenderer {
243215
writer.write('`');
244216
break;
245217
case 'api-link':
246-
if (!context.options.onRenderApiLink) {
247-
throw new Error('IMarkupApiLink cannot be rendered because a renderApiLink handler was not provided');
248-
}
249-
250-
const args: IMarkdownRenderApiLinkArgs = {
251-
reference: element.target,
252-
prefix: '',
253-
suffix: ''
254-
};
255-
256-
// NOTE: The onRenderApiLink() callback will assign values to the args.prefix
257-
// and args.suffix properties, which are used below. (It is modeled this way because
258-
// MarkdownRenderer._writeElements() may need to emit different escaping e.g. depending
259-
// on what characters were written by writer.write(args.prefix).)
260-
context.options.onRenderApiLink(args);
261-
262-
if (args.prefix) {
263-
writer.write(args.prefix);
264-
}
218+
writer.write('[');
265219
MarkdownRenderer._writeElements(element.elements, context);
266-
if (args.suffix) {
267-
writer.write(args.suffix);
268-
}
269-
220+
writer.write(`](${element.target})`);
270221
break;
271222
case 'web-link':
272223
writer.write('[');

‎apps/api-documenter/src/utils/Markup.ts‎

Lines changed: 2 additions & 155 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 { PackageName } from '@microsoft/node-core-library';
54
import {
65
MarkupElement,
76
MarkupBasicElement,
@@ -24,8 +23,6 @@ import {
2423
MarkupHighlighter
2524
} from './MarkupElement';
2625

27-
import { IApiItemReference } from '../api/ApiItem';
28-
2926
/**
3027
* Options for {@link Markup.createTextElements}
3128
*
@@ -166,18 +163,11 @@ export class Markup {
166163
* @param textElements - the markup sequence that will serve as the link text
167164
* @param target - the API object that the hyperlink will point to
168165
*/
169-
public static createApiLink(textElements: MarkupLinkTextElement[], target: IApiItemReference): IMarkupApiLink {
166+
public static createApiLink(textElements: MarkupLinkTextElement[], target: string): IMarkupApiLink {
170167
if (!textElements.length) {
171168
throw new Error('Missing text for link');
172169
}
173170

174-
if (!target.packageName || target.packageName.length < 1) {
175-
throw new Error('The IApiItemReference.packageName cannot be empty');
176-
}
177-
178-
// Validate that the scopeName and packageName are formatted correctly
179-
PackageName.combineParts(target.scopeName, target.packageName);
180-
181171
return {
182172
kind: 'api-link',
183173
elements: textElements,
@@ -191,7 +181,7 @@ export class Markup {
191181
* @param text - the text string that will serve as the link text
192182
* @param target - the API object that the hyperlink will point to
193183
*/
194-
public static createApiLinkFromText(text: string, target: IApiItemReference): IMarkupApiLink {
184+
public static createApiLinkFromText(text: string, target: string): IMarkupApiLink {
195185
return Markup.createApiLink(Markup.createTextElements(text), target);
196186
}
197187

@@ -357,149 +347,6 @@ export class Markup {
357347
} as IMarkupPage;
358348
}
359349

360-
/**
361-
* Extracts plain text from the provided markup elements, discarding any formatting.
362-
*
363-
* @remarks
364-
* The returned string is suitable for counting words or extracting search keywords.
365-
* Its formatting is not guaranteed, and may change in future updates of this API.
366-
*
367-
* API Extractor determines whether an API is "undocumented" by using extractTextContent()
368-
* to extract the text from its summary, and then counting the number of words.
369-
*/
370-
public static extractTextContent(elements: MarkupElement[]): string {
371-
// Pass a buffer, since "+=" uses less memory than "+"
372-
const buffer: { text: string } = { text: '' };
373-
Markup._extractTextContent(elements, buffer);
374-
return buffer.text;
375-
}
376-
377-
/**
378-
* Use this to clean up a MarkupElement sequence, assuming the sequence is now in
379-
* its final form.
380-
*
381-
* @remarks
382-
* The following operations are performed:
383-
*
384-
* 1. Remove leading/trailing white space around paragraphs
385-
*
386-
* 2. Remove redundant paragraph elements
387-
*/
388-
public static normalize<T extends MarkupElement>(elements: T[]): void {
389-
let i: number = 0;
390-
391-
while (i < elements.length) {
392-
const element: T = elements[i];
393-
const previousElement: T | undefined = i - 1 >= 0 ? elements[i - 1] : undefined;
394-
const nextElement: T | undefined = i + 1 < elements.length ? elements[i + 1] : undefined;
395-
396-
const paragraphBefore: boolean = !!(previousElement && previousElement.kind === 'paragraph');
397-
const paragraphAfter: boolean = !!(nextElement && nextElement.kind === 'paragraph');
398-
399-
if (element.kind === 'paragraph') {
400-
if (i === 0 || i === elements.length - 1 || paragraphBefore) {
401-
// Delete this element. We do not update i because the "previous" item
402-
// is unchanged on the next loop.
403-
elements.splice(i, 1);
404-
continue;
405-
}
406-
} else if (element.kind === 'text') {
407-
const textElement: IMarkupText = element as IMarkupText;
408-
if (paragraphBefore || i === 0) {
409-
textElement.text = textElement.text.replace(/^\s+/, ''); // trim left
410-
}
411-
412-
if (paragraphAfter || i === elements.length - 1) {
413-
textElement.text = textElement.text.replace(/\s+$/, ''); // trim right
414-
}
415-
}
416-
417-
++i;
418-
}
419-
}
420-
421-
/**
422-
* This formats an IApiItemReference as its AEDoc notation.
423-
*
424-
* @remarks
425-
* Depending on the provided components, example return values might look like
426-
* "\@ms/my-library:SomeClass.someProperty", "my-library:SomeClass", "SomeClass",
427-
* or "SomeClass.someProperty".
428-
*/
429-
public static formatApiItemReference(apiItemReference: IApiItemReference): string {
430-
// Example: "SomeClass"
431-
let result: string = apiItemReference.exportName;
432-
if (apiItemReference.packageName) {
433-
// Example: "my-library:SomeClass"
434-
result = apiItemReference.packageName + '#' + result;
435-
436-
if (apiItemReference.scopeName) {
437-
// Example: "@ms/my-library:SomeClass"
438-
result = apiItemReference.scopeName + '/' + result;
439-
}
440-
}
441-
if (apiItemReference.memberName) {
442-
// Example: "@ms/my-library:SomeClass.someProperty"
443-
result += '.' + apiItemReference.memberName;
444-
}
445-
return result;
446-
}
447-
448-
private static _extractTextContent(elements: MarkupElement[], buffer: { text: string }): void {
449-
for (const element of elements) {
450-
switch (element.kind) {
451-
case 'api-link':
452-
buffer.text += Markup.extractTextContent(element.elements);
453-
break;
454-
case 'break':
455-
buffer.text += '\n';
456-
break;
457-
case 'code':
458-
case 'code-box':
459-
buffer.text += element.text;
460-
break;
461-
case 'heading1':
462-
case 'heading2':
463-
buffer.text += element.text;
464-
break;
465-
case 'html-tag':
466-
break;
467-
case 'note-box':
468-
buffer.text += Markup.extractTextContent(element.elements);
469-
break;
470-
case 'page':
471-
buffer.text += element.title + '\n';
472-
buffer.text += Markup.extractTextContent(element.elements);
473-
break;
474-
case 'paragraph':
475-
buffer.text += '\n\n';
476-
break;
477-
case 'table':
478-
if (element.header) {
479-
buffer.text += Markup.extractTextContent([element.header]);
480-
}
481-
buffer.text += Markup.extractTextContent(element.rows);
482-
break;
483-
case 'table-cell':
484-
buffer.text += Markup.extractTextContent(element.elements);
485-
buffer.text += '\n';
486-
break;
487-
case 'table-row':
488-
buffer.text += Markup.extractTextContent(element.cells);
489-
buffer.text += '\n';
490-
break;
491-
case 'text':
492-
buffer.text += element.text;
493-
break;
494-
case 'web-link':
495-
buffer.text += Markup.extractTextContent(element.elements);
496-
break;
497-
default:
498-
throw new Error('Unsupported element kind');
499-
}
500-
}
501-
}
502-
503350
private static _trimRawText(text: string): string {
504351
// Replace multiple whitespaces with a single space
505352
return text.replace(/\s+/g, ' ');

‎apps/api-documenter/src/utils/MarkupElement.ts‎

Lines changed: 3 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +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 { IApiItemReference } from '../api/ApiItem';
5-
64
// ----------------------------------------------------------------------------
75

86
/**
@@ -106,8 +104,8 @@ export interface IMarkupApiLink {
106104
/** The link text */
107105
elements: MarkupLinkTextElement[];
108106

109-
/** The API item that will serve as the hyperlink target */
110-
target: IApiItemReference;
107+
/** The string that will serve as the target for the Markdown-style hyperlink */
108+
target: string;
111109
}
112110

113111
/**
@@ -121,7 +119,7 @@ export interface IMarkupWebLink {
121119
/** The link text */
122120
elements: MarkupLinkTextElement[];
123121

124-
/** The internet URL that will serve as the hyperlink target */
122+
/** The internet URL that will serve as target for the HTML-style hyperlink */
125123
targetUrl: string;
126124
}
127125

‎apps/api-documenter/src/utils/test/MarkdownRenderer.test.ts‎

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

44
import * as path from 'path';
55
import { FileDiffTest, FileSystem } from '@microsoft/node-core-library';
6-
import { IMarkupPage, Markup } from '@microsoft/api-extractor';
6+
import { Markup } from '../Markup';
7+
import { IMarkupPage } from '../MarkupElement';
78

89
import { MarkdownRenderer } from '../MarkdownRenderer';
910

@@ -65,7 +66,7 @@ describe('MarkdownPageRenderer', () => {
6566
]);
6667

6768
const outputFilename: string = path.join(outputFolder, 'ActualOutput.md');
68-
FileSystem.writeFile(outputFilename, MarkdownRenderer.renderElements([markupPage], { }));
69+
FileSystem.writeFile(outputFilename, MarkdownRenderer.renderElements([markupPage]));
6970

7071
FileDiffTest.assertEqual(outputFilename, path.join(__dirname, 'ExpectedOutput.md'));
7172

0 commit comments

Comments
 (0)