Add missing API reference for validators (#273)

l2beat · Mar 31, 2023 · 238d49c · 238d49c
1 parent 5d17741
commit 238d49c
Show file tree

Hide file tree

Showing 5 changed files with 34 additions and 14 deletions.
diff --git a/packages/earl/src/validators/other/toBeRejectedWith.ts b/packages/earl/src/validators/other/toBeRejectedWith.ts
@@ -34,7 +34,6 @@ declare module '../../expect' {
      * The result of this validator is a promise, so you can need to use it with
      * `await`.
      *
-     * @param errorClass - The error class to check.
      * @param message - A substring of the error message or a regex matching the
      *   message.
      *

diff --git a/packages/earl/src/validators/other/toThrow.ts b/packages/earl/src/validators/other/toThrow.ts
@@ -13,7 +13,6 @@ declare module '../../expect' {
      * This validator does not support async functions. Use `toBeRejected` and
      * `toBeRejectedWith` instead.
      *
-     * @param errorClass - The error class to check.
      * @param message - A substring of the error message or a regex matching the
      *   message.
      *

diff --git a/packages/website/generators/api-reference/index.ts b/packages/website/generators/api-reference/index.ts
@@ -17,7 +17,7 @@ async function main() {
   const reference = await generateApiReference({
     basePath: path.resolve(__dirname, '../../../earl/dist/cjs'),
     files: [
-      'Validators::validators/**/toBeA.d.ts', // replace with once more docs for validators are written: 'Validators:validators:validators/**/*.d.ts',
+      'Validators::validators/**/*.d.ts',
       'Matchers:expect:matchers/**/*.d.ts',
       'Mocks:mock:mocks/mockFn.d.ts,mocks/types/index.d.ts',
     ],

diff --git a/packages/website/generators/api-reference/tsdocs/extract.test.ts b/packages/website/generators/api-reference/tsdocs/extract.test.ts
@@ -6,7 +6,7 @@ describe('extractTsDocCommentsFromString', () => {
   it('extracts single method comment', () => {
     const input = `
     /** test */
-    someMethod(): void {}
+    someMethod(): void;
     `
     const comments = extractTsDocCommentsFromString(input)
 
@@ -18,7 +18,7 @@ describe('extractTsDocCommentsFromString', () => {
   it('extracts single getter comment', () => {
     const input = `
     /** test */
-    get someMethod(): void {}
+    get someMethod(): void;
     `
     const comments = extractTsDocCommentsFromString(input)
 
@@ -30,9 +30,9 @@ describe('extractTsDocCommentsFromString', () => {
   it('extracts multiple method comments', () => {
     const input = `
     /** test */
-    someMethod(): void {}
+    someMethod(): void;
     /** test2 */
-    totallyDifferentMethod(): void {}
+    totallyDifferentMethod(): void;
     `
     const comments = extractTsDocCommentsFromString(input)
 
@@ -45,9 +45,9 @@ describe('extractTsDocCommentsFromString', () => {
   it('extracts multiple method comments from overrides', () => {
     const input = `
     /** test */
-    someMethod(): void
+    someMethod(): void;
     /** test2 */
-    someMethod(arg1: number): void
+    someMethod(arg1: number): void;
     `
     const comments = extractTsDocCommentsFromString(input)
 
@@ -57,10 +57,10 @@ describe('extractTsDocCommentsFromString', () => {
     ])
   })
 
-  it.skip('extracts given inline object literal type', () => {
+  it('extracts given inline object literal type', () => {
     const input = `
       /** boop */
-      method(args: { a: number, b: number }): void
+      method(args: { a: number, b: number }): void;
     `
 
     expect(extractTsDocCommentsFromString(input)).toEqual([
@@ -71,13 +71,13 @@ describe('extractTsDocCommentsFromString', () => {
     ])
   })
 
-  it.skip('handles multiline signatures', () => {
+  it('handles multiline signatures', () => {
     const input = `
       /** boop */
       method(args: {
         a: number,
         b: number
-      }): void
+      }): void;
     `
 
     expect(extractTsDocCommentsFromString(input)).toEqual([
@@ -101,4 +101,22 @@ describe('extractTsDocCommentsFromString', () => {
       },
     ])
   })
+
+  it('handles multiline signatures with union types and generics', () => {
+    const input = `
+      /** boop */
+      toHaveLength(
+        this: Validators<string | any[] | { length: number }>,
+        length: number,
+      ): void;
+    `
+
+    expect(extractTsDocCommentsFromString(input)).toEqual([
+      {
+        signature:
+          'toHaveLength(this: Validators<string | any[] | { length: number }>, length: number): void',
+        comment: '/** boop */',
+      },
+    ])
+  })
 })
diff --git a/packages/website/generators/api-reference/tsdocs/extract.ts b/packages/website/generators/api-reference/tsdocs/extract.ts
@@ -8,7 +8,7 @@ export function extractTsDocCommentsFromString(
 ): MethodComment[] {
   // @todo use TypeScript's parser to extract signatures and comments
   // We have a few bugs already — see skipped tests in extract.test.ts
-  const DOC_COMMENT_REGEX = /\/\*\*([\s\S]*?)\*\/[\n\r]+([\s\S]*?)[{;\n\r]+/gm
+  const DOC_COMMENT_REGEX = /\/\*\*([\s\S]*?)\*\/[\n\r]+([\s\S]*?);+/gm
 
   const methodComments: MethodComment[] = []
 
@@ -22,6 +22,10 @@ export function extractTsDocCommentsFromString(
     const comment = `/** ${rawMethodComment[1]!.trim()} */`
     // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
     let signature = removeGetterKeyword(rawMethodComment[2]!.trim())
+    signature = signature.replace(/\n/g, '')
+    signature = signature.replace(/[ ]+/g, ' ')
+    signature = signature.replace(/,[ ]?\)/g, ')')
+    signature = signature.replace(/\( /g, '(')
 
     if (signature.endsWith(';')) signature = signature.slice(0, -1)