feat: parse class descriptions (#25)

* feat: parse class descriptions

* spec: add tests for code fence parsing

* feat: parse module descriptions

Author: MarshallOfSound

src/DocsParser.ts

@@ -24,6 +24,10 @@ import {
   findConstructorHeader,
   consumeTypedKeysList,
   findProcess,
+  getContentBeforeConstructor,
+  findContentAfterHeadingClose,
+  HeadingContent,
+  getContentBeforeFirstHeadingMatching,
 } from './markdown-helpers';
 import { WEBSITE_BASE_DOCS_URL, REPO_BASE_DOCS_URL } from './constants';
 import { extendError } from './helpers';
@@ -94,7 +98,26 @@ export class DocsParser {
         if (isStructure) {
           description = safelyJoinTokens(findContentAfterList(tokens));
         } else {
-          // TODO: Pull the top level Module / Class description
+          let groups: HeadingContent[];
+          if (isClass) {
+            groups = getContentBeforeConstructor(tokens);
+          } else {
+            // FIXME: Make it so that we don't need this magic FIXME for the electron breaking-changes document
+            groups = getContentBeforeFirstHeadingMatching(tokens, heading =>
+              ['Events', 'Methods', 'Properties', '`FIXME` comments'].includes(heading.trim()),
+            );
+          }
+          description = groups
+            .map((group, index) => {
+              const inner = safelyJoinTokens(findContentAfterHeadingClose(group.content), {
+                parseCodeFences: true,
+              });
+              if (index !== 0) {
+                return `### ${group.heading}\n\n${inner}`;
+              }
+              return inner;
+            })
+            .join('\n\n');
         }
 
         const extendsMatch = / Object extends `(.+?)`?$/.exec(heading.heading);

src/__tests__/__snapshots__/markdown-helpers.spec.ts.snap

@@ -334,3 +334,18 @@ exports[`markdown-helpers safelyJoinTokens snapshots should be correct for parag
 exports[`markdown-helpers safelyJoinTokens snapshots should be correct for paragraph-with-links 1`] = `"This paragraph has a bunch of stuff.  Also some links Foo, these links should be stripped."`;
 
 exports[`markdown-helpers safelyJoinTokens snapshots should be correct for paragraph-with-text-markers 1`] = `"Heya, this is **bold** and _italic_ and *italic* and ~~struck through~~"`;
+
+exports[`markdown-helpers safelyJoinTokens with code fence support should correctly insert the code fence 1`] = `
+"> a
+
+\`\`\`
+wat
+
+def fn():
+  pass
+
+# a
+\`\`\`
+
+> foo"
+`;

src/__tests__/markdown-helpers.spec.ts

@@ -67,6 +67,28 @@ describe('markdown-helpers', () => {
         });
       }
     });
+
+    describe('with code fence support', () => {
+      it('should correctly insert the code fence', () => {
+        const tokens = getTokens(
+          `
+> a
+
+\`\`\`
+wat
+
+def fn():
+  pass
+
+# a
+\`\`\`
+
+> foo
+`,
+        );
+        expect(safelyJoinTokens(tokens, { parseCodeFences: true })).toMatchSnapshot();
+      });
+    });
   });
 
   describe('extractStringEnum()', () => {

src/markdown-helpers.ts

@@ -139,14 +139,36 @@ export const headingsAndContent = (tokens: Token[]): HeadingContent[] => {
   return groups;
 };
 
+const getConstructorHeaderInGroups = (groups: HeadingContent[]) => {
+  return groups.find(group => group.heading.startsWith('`new ') && group.level === 3);
+};
+
 export const findConstructorHeader = (tokens: Token[]) => {
   const groups = headingsAndContent(tokens);
-  const constructorHeader = groups.find(
-    group => group.heading.startsWith('`new ') && group.level === 3,
-  );
+  const constructorHeader = getConstructorHeaderInGroups(groups);
   return constructorHeader ? constructorHeader : null;
 };
 
+export const getContentBeforeConstructor = (tokens: Token[]) => {
+  const groups = headingsAndContent(tokens);
+  const constructorHeader = getConstructorHeaderInGroups(groups);
+  if (!constructorHeader) return [];
+
+  return groups.slice(0, groups.indexOf(constructorHeader));
+};
+
+export const getContentBeforeFirstHeadingMatching = (
+  tokens: Token[],
+  matcher: (heading: string) => boolean,
+) => {
+  const groups = headingsAndContent(tokens);
+
+  return groups.slice(
+    0,
+    groups.findIndex(g => matcher(g.heading)),
+  );
+};
+
 export const findContentInsideHeader = (
   tokens: Token[],
   expectedHeader: string,
@@ -461,13 +483,17 @@ export const extractReturnType = (
   };
 };
 
+export interface JoinTokenOptions {
+  parseCodeFences?: boolean;
+}
+
 // NOTE: This method obliterates code fences
-export const safelyJoinTokens = (tokens: Token[]) => {
+export const safelyJoinTokens = (tokens: Token[], options: JoinTokenOptions = {}) => {
   let joinedContent = '';
   let listLevel = -1;
   for (const tokenToCheck of tokens) {
     if (tokenToCheck.children !== null && tokenToCheck.type === 'inline') {
-      joinedContent += safelyJoinTokens(tokenToCheck.children);
+      joinedContent += safelyJoinTokens(tokenToCheck.children, options);
       continue;
     }
     expect(tokenToCheck.children).to.equal(
@@ -557,7 +583,11 @@ export const safelyJoinTokens = (tokens: Token[]) => {
         break;
       case 'paragraph_open':
       case 'blockquote_close':
+        break;
       case 'fence':
+        if (options.parseCodeFences) {
+          joinedContent += `\`\`\`\n${tokenToCheck.content}\`\`\`\n\n`;
+        }
         break;
       default:
         expect(false).to.equal(true, 'unreachable default switch case');