Skip to content

Commit

Permalink
Merge branch 'main' into docs-disable-algolia
Browse files Browse the repository at this point in the history
  • Loading branch information
Shinigami92 authored Mar 7, 2022
2 parents c0012db + c99160f commit 793af67
Show file tree
Hide file tree
Showing 8 changed files with 325 additions and 3 deletions.
5 changes: 3 additions & 2 deletions scripts/apidoc/directMethods.ts
Original file line number Diff line number Diff line change
Expand Up @@ -41,8 +41,9 @@ export function processDirectMethod(
methodName.substring(0, 1).toUpperCase() + methodName.substring(1);
console.log(`Processing Direct: ${upperMethodName}`);

const signature = (direct.type as TypeDoc.ReflectionType).declaration
.signatures[0];
const signatures = (direct.type as TypeDoc.ReflectionType).declaration
.signatures;
const signature = signatures[signatures.length - 1];

writeApiDocsDirectPage(methodName);
writeApiDocsData(methodName, [
Expand Down
3 changes: 2 additions & 1 deletion scripts/apidoc/moduleMethods.ts
Original file line number Diff line number Diff line change
Expand Up @@ -50,7 +50,8 @@ function processModuleMethod(module: TypeDoc.DeclarationReflection): PageIndex {
)) {
const methodName = method.name;
console.debug(`- ${methodName}`);
const signature = method.signatures[0];
const signatures = method.signatures;
const signature = signatures[signatures.length - 1];

methods.push(analyzeSignature(signature, lowerModuleName, methodName));
}
Expand Down
20 changes: 20 additions & 0 deletions src/random.ts
Original file line number Diff line number Diff line change
Expand Up @@ -179,6 +179,26 @@ export class Random {
object: T,
field?: unknown
): T[K];
/**
* Returns a random key or value from given object.
*
* @template T The type of `Record` to pick from.
* @template K The keys of `T`.
* @param object The object to get the keys or values from.
* @param field If this is set to `'key'`, this method will a return a random key of the given instance.
* If this is set to `'value'`, this method will a return a random value of the given instance.
* Defaults to `'value'`.
*
* @example
* const object = { keyA: 'valueA', keyB: 42 };
* faker.random.objectElement(object) // 42
* faker.random.objectElement(object, 'key') // 'keyB'
* faker.random.objectElement(object, 'value') // 'valueA'
*/
objectElement<T extends Record<string, unknown>, K extends keyof T>(
object: T,
field?: 'key' | 'value'
): K | T[K];
objectElement<T extends Record<string, unknown>, K extends keyof T>(
object = { foo: 'bar', too: 'car' } as unknown as T,
field = 'value'
Expand Down
1 change: 1 addition & 0 deletions test/scripts/apidoc/.gitignore
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
*.actuals.json
88 changes: 88 additions & 0 deletions test/scripts/apidoc/signature.example.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,88 @@
export class SignatureTest {
/**
* Test with no parameters.
*/
noParamMethod(): number {
return 0;
}

/**
* Test with a required parameter.
*
* @param a The number parameter.
*/
requiredNumberParamMethod(a: number): number {
return a;
}

/**
* Test with an optional parameter.
*
* @param b The string parameter.
*/
optionalStringParamMethod(b?: string): number {
return +b;
}

/**
* Test with a default parameter.
*
* @param c The boolean parameter.
*/
defaultBooleanParamMethod(c: boolean = true): number {
return c ? 1 : 0;
}

/**
* Test with multiple parameters.
*
* @param a The number parameter.
* @param b The string parameter.
* @param c The boolean parameter.
*/
multiParamMethod(a: number, b?: string, c: boolean = true): number {
return c ? a : +b;
}

/**
* Test with a function parameters.
*
* @param fn The function parameter.
*/
functionParamMethod(fn: (a: string) => number): number {
return fn('a');
}

/**
* Test with a function parameters.
*
* @param options The function parameter.
* @param options.a The number parameter.
* @param options.b The string parameter.
* @param options.c The boolean parameter.
*/
optionsParamMethod(options: { a: number; b?: string; c: boolean }): number {
return options.c ? options.a : +options.b;
}

/**
* Test with example marker.
*
* @example
* test.apidoc.methodWithExample() // 0
*/
methodWithExample(): number {
return 0;
}

/**
* Test with deprecated and see marker.
*
* @see test.apidoc.methodWithExample()
*
* @deprecated
*/
methodWithDeprecated(): number {
return 0;
}
}
155 changes: 155 additions & 0 deletions test/scripts/apidoc/signature.expected.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,155 @@
{
"noParamMethod": {
"name": "noParamMethod",
"title": "No Param Method",
"description": "<p>Test with no parameters.</p>\n",
"parameters": [],
"returns": "number",
"examples": "<div class=\"language-ts\"><pre v-pre><code>faker<span class=\"token punctuation\">.</span><span class=\"token function\">noParamMethod</span><span class=\"token punctuation\">(</span><span class=\"token punctuation\">)</span><span class=\"token operator\">:</span> <span class=\"token builtin\">number</span>\n</code></pre>\n</div>",
"deprecated": false,
"seeAlsos": []
},
"defaultBooleanParamMethod": {
"name": "defaultBooleanParamMethod",
"title": "Default Boolean Param Method",
"description": "<p>Test with a default parameter.</p>\n",
"parameters": [
{
"name": "c",
"type": "boolean",
"default": "true",
"description": "<p>The boolean parameter.</p>\n"
}
],
"returns": "number",
"examples": "<div class=\"language-ts\"><pre v-pre><code>faker<span class=\"token punctuation\">.</span><span class=\"token function\">defaultBooleanParamMethod</span><span class=\"token punctuation\">(</span>c<span class=\"token operator\">:</span> <span class=\"token builtin\">boolean</span> <span class=\"token operator\">=</span> <span class=\"token boolean\">true</span><span class=\"token punctuation\">)</span><span class=\"token operator\">:</span> <span class=\"token builtin\">number</span>\n</code></pre>\n</div>",
"deprecated": false,
"seeAlsos": []
},
"functionParamMethod": {
"name": "functionParamMethod",
"title": "Function Param Method",
"description": "<p>Test with a function parameters.</p>\n",
"parameters": [
{
"name": "fn",
"type": "Function",
"description": "<p>The function parameter.</p>\n"
}
],
"returns": "number",
"examples": "<div class=\"language-ts\"><pre v-pre><code>faker<span class=\"token punctuation\">.</span><span class=\"token function\">functionParamMethod</span><span class=\"token punctuation\">(</span>fn<span class=\"token operator\">:</span> <span class=\"token builtin\">Function</span><span class=\"token punctuation\">)</span><span class=\"token operator\">:</span> <span class=\"token builtin\">number</span>\n</code></pre>\n</div>",
"deprecated": false,
"seeAlsos": []
},
"methodWithDeprecated": {
"name": "methodWithDeprecated",
"title": "Method With Deprecated",
"description": "<p>Test with deprecated and see marker.</p>\n",
"parameters": [],
"returns": "number",
"examples": "<div class=\"language-ts\"><pre v-pre><code>faker<span class=\"token punctuation\">.</span><span class=\"token function\">methodWithDeprecated</span><span class=\"token punctuation\">(</span><span class=\"token punctuation\">)</span><span class=\"token operator\">:</span> <span class=\"token builtin\">number</span>\n</code></pre>\n</div>",
"deprecated": true,
"seeAlsos": ["test.apidoc.methodWithExample()"]
},
"methodWithExample": {
"name": "methodWithExample",
"title": "Method With Example",
"description": "<p>Test with example marker.</p>\n",
"parameters": [],
"returns": "number",
"examples": "<div class=\"language-ts\"><pre v-pre><code>faker<span class=\"token punctuation\">.</span><span class=\"token function\">methodWithExample</span><span class=\"token punctuation\">(</span><span class=\"token punctuation\">)</span><span class=\"token operator\">:</span> <span class=\"token builtin\">number</span>\ntest<span class=\"token punctuation\">.</span>apidoc<span class=\"token punctuation\">.</span><span class=\"token function\">methodWithExample</span><span class=\"token punctuation\">(</span><span class=\"token punctuation\">)</span> <span class=\"token comment\">// 0</span>\n</code></pre>\n</div>",
"deprecated": false,
"seeAlsos": []
},
"multiParamMethod": {
"name": "multiParamMethod",
"title": "Multi Param Method",
"description": "<p>Test with multiple parameters.</p>\n",
"parameters": [
{
"name": "a",
"type": "number",
"description": "<p>The number parameter.</p>\n"
},
{
"name": "b?",
"type": "string",
"description": "<p>The string parameter.</p>\n"
},
{
"name": "c",
"type": "boolean",
"default": "true",
"description": "<p>The boolean parameter.</p>\n"
}
],
"returns": "number",
"examples": "<div class=\"language-ts\"><pre v-pre><code>faker<span class=\"token punctuation\">.</span><span class=\"token function\">multiParamMethod</span><span class=\"token punctuation\">(</span>a<span class=\"token operator\">:</span> <span class=\"token builtin\">number</span><span class=\"token punctuation\">,</span> b<span class=\"token operator\">?</span><span class=\"token operator\">:</span> <span class=\"token builtin\">string</span><span class=\"token punctuation\">,</span> c<span class=\"token operator\">:</span> <span class=\"token builtin\">boolean</span> <span class=\"token operator\">=</span> <span class=\"token boolean\">true</span><span class=\"token punctuation\">)</span><span class=\"token operator\">:</span> <span class=\"token builtin\">number</span>\n</code></pre>\n</div>",
"deprecated": false,
"seeAlsos": []
},
"optionalStringParamMethod": {
"name": "optionalStringParamMethod",
"title": "Optional String Param Method",
"description": "<p>Test with an optional parameter.</p>\n",
"parameters": [
{
"name": "b?",
"type": "string",
"description": "<p>The string parameter.</p>\n"
}
],
"returns": "number",
"examples": "<div class=\"language-ts\"><pre v-pre><code>faker<span class=\"token punctuation\">.</span><span class=\"token function\">optionalStringParamMethod</span><span class=\"token punctuation\">(</span>b<span class=\"token operator\">?</span><span class=\"token operator\">:</span> <span class=\"token builtin\">string</span><span class=\"token punctuation\">)</span><span class=\"token operator\">:</span> <span class=\"token builtin\">number</span>\n</code></pre>\n</div>",
"deprecated": false,
"seeAlsos": []
},
"optionsParamMethod": {
"name": "optionsParamMethod",
"title": "Options Param Method",
"description": "<p>Test with a function parameters.</p>\n",
"parameters": [
{
"name": "options",
"type": "Object",
"description": "<p>The function parameter.</p>\n"
},
{
"name": "options.a",
"type": "number",
"description": "<p>The number parameter.</p>\n"
},
{
"name": "options.b?",
"type": "string",
"description": "<p>The string parameter.</p>\n"
},
{
"name": "options.c",
"type": "boolean",
"description": "<p>The boolean parameter.</p>\n"
}
],
"returns": "number",
"examples": "<div class=\"language-ts\"><pre v-pre><code>faker<span class=\"token punctuation\">.</span><span class=\"token function\">optionsParamMethod</span><span class=\"token punctuation\">(</span>options<span class=\"token operator\">:</span> Object<span class=\"token punctuation\">)</span><span class=\"token operator\">:</span> <span class=\"token builtin\">number</span>\n</code></pre>\n</div>",
"deprecated": false,
"seeAlsos": []
},
"requiredNumberParamMethod": {
"name": "requiredNumberParamMethod",
"title": "Required Number Param Method",
"description": "<p>Test with a required parameter.</p>\n",
"parameters": [
{
"name": "a",
"type": "number",
"description": "<p>The number parameter.</p>\n"
}
],
"returns": "number",
"examples": "<div class=\"language-ts\"><pre v-pre><code>faker<span class=\"token punctuation\">.</span><span class=\"token function\">requiredNumberParamMethod</span><span class=\"token punctuation\">(</span>a<span class=\"token operator\">:</span> <span class=\"token builtin\">number</span><span class=\"token punctuation\">)</span><span class=\"token operator\">:</span> <span class=\"token builtin\">number</span>\n</code></pre>\n</div>",
"deprecated": false,
"seeAlsos": []
}
}
53 changes: 53 additions & 0 deletions test/scripts/apidoc/signature.spec.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,53 @@
import { writeFileSync } from 'fs';
import { resolve } from 'path';
import * as TypeDoc from 'typedoc';
import { afterAll, describe, expect, it } from 'vitest';
import type { Method } from '../../../docs/.vitepress/components/api-docs/method';
import { analyzeSignature } from '../../../scripts/apidoc/signature';
import expected_ from './signature.expected.json';
const expected: Record<string, Method> = expected_;

function prettyJson(object): string {
return JSON.stringify(object, null, 2);
}

describe('signature', () => {
const app = new TypeDoc.Application();

app.options.addReader(new TypeDoc.TSConfigReader());

app.bootstrap({
entryPoints: ['test/scripts/apidoc/signature.example.ts'],
tsconfig: 'test/scripts/apidoc/tsconfig.json',
});

const methods: Record<string, TypeDoc.DeclarationReflection> = app
.convert()
.getChildrenByKind(TypeDoc.ReflectionKind.Class)[0]
.getChildrenByKind(TypeDoc.ReflectionKind.Method)
.reduce((a, v) => ({ ...a, [v.name]: v }), {});

describe('analyzeSignature()', () => {
const actuals = {};

it('expected and actual methods are equal', () => {
expect(Object.keys(methods).sort()).toEqual(Object.keys(expected).sort());
});

it.each(Object.keys(expected))('%s', (name) => {
const method = methods[name];
const actual = analyzeSignature(method.signatures[0], null, method.name);
actuals[name] = actual;

expect(prettyJson(actual)).toBe(prettyJson(expected[name]));
});

afterAll(() => {
// Write to file for easier comparison
writeFileSync(
resolve('test', 'scripts', 'apidoc', 'signature.actuals.json'),
prettyJson(actuals)
);
});
});
});
3 changes: 3 additions & 0 deletions test/scripts/apidoc/tsconfig.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
{
"include": ["signature.example.ts"]
}

0 comments on commit 793af67

Please sign in to comment.