feat(docs): generate docs for slots (#1363)

fixes #1362

Author: manucorporat

src/compiler/docs/generate-doc-data.ts

@@ -52,6 +52,7 @@ async function getComponents(config: d.Config, compilerCtx: d.CompilerCtx, diagn
         .filter(([_, member]) => isDocsPublic(member.jsdoc));
 
       const readme = await getUserReadmeContent(compilerCtx, readmePath);
+      const docsTags = generateDocsTags(moduleFile.cmpMeta.jsdoc);
 
       return {
         dirPath,
@@ -61,15 +62,16 @@ async function getComponents(config: d.Config, compilerCtx: d.CompilerCtx, diagn
         usagesDir,
         tag: moduleFile.cmpMeta.tagNameMeta,
         readme,
+        docsTags,
         docs: generateDocs(readme, moduleFile.cmpMeta.jsdoc),
-        docsTags: generateDocsTags(moduleFile.cmpMeta.jsdoc),
         usage: await generateUsages(config, compilerCtx, usagesDir),
         encapsulation: getEncapsulation(moduleFile.cmpMeta),
 
         props: getProperties(membersMeta),
         methods: getMethods(membersMeta),
         events: getEvents(moduleFile.cmpMeta),
-        styles: getStyles(moduleFile.cmpMeta)
+        styles: getStyles(moduleFile.cmpMeta),
+        slots: getSlots(docsTags)
       };
     });
   return Promise.all(promises);
@@ -170,6 +172,22 @@ function getStyles(cmpMeta: d.ComponentMeta): d.JsonDocsStyle[] {
   });
 }
 
+function getSlots(tags: d.JsonDocsTags[]): d.JsonDocsSlot[] {
+  return tags
+    .filter(tag => tag.name === 'slot' && tag.text)
+    .map(({text}) => {
+      const [namePart, ...rest] = (' ' + text).split(' - ');
+      return {
+        name: namePart.trim(),
+        docs: rest.join(' - ').trim()
+      };
+    })
+    .sort((a, b) => {
+      if (a.name.toLowerCase() < b.name.toLowerCase()) return -1;
+      if (a.name.toLowerCase() > b.name.toLowerCase()) return 1;
+      return 0;
+    });
+}
 
 function getAttrName(memberMeta: d.MemberMeta) {
   if (memberMeta.attribName) {

src/compiler/docs/generate-json-docs.ts

@@ -14,6 +14,7 @@ export async function generateJsonDocs(compilerCtx: d.CompilerCtx, jsonOutputs:
       methods: cmp.methods,
       events: cmp.events,
       styles: cmp.styles,
+      slots: cmp.slots
     }))
   };
   const jsonContent = JSON.stringify(json, null, 2);

src/compiler/docs/generate-readme-docs.ts

@@ -5,6 +5,7 @@ import { eventsToMarkdown } from './markdown-events';
 import { methodsToMarkdown } from './markdown-methods';
 import { usageToMarkdown } from './markdown-usage';
 import { stylesToMarkdown } from './markdown-css-props';
+import { slotsToMarkdown } from './markdown-slots';
 
 export async function generateReadmeDocs(config: d.Config, compilerCtx: d.CompilerCtx, readmeOutputs: d.OutputTargetDocsReadme[], docs: d.JsonDocs) {
   await Promise.all(docs.components.map(async cmpData => {
@@ -44,6 +45,7 @@ export function generateMarkdown(userContent: string, cmp: d.JsonDocsComponent)
     ...propsToMarkdown(cmp.props),
     ...eventsToMarkdown(cmp.events),
     ...methodsToMarkdown(cmp.methods),
+    ...slotsToMarkdown(cmp.slots),
     ...stylesToMarkdown(cmp.styles),
     `----------------------------------------------`,
     '',

src/compiler/docs/markdown-slots.ts

@@ -0,0 +1,29 @@
+import * as d from '../../declarations';
+import { MarkdownTable } from './docs-util';
+
+
+export function slotsToMarkdown(slots: d.JsonDocsSlot[]) {
+  const content: string[] = [];
+  if (slots.length === 0) {
+    return content;
+  }
+
+  content.push(`## Slots`);
+  content.push(``);
+
+  const table = new MarkdownTable();
+  table.addHeader(['Slot', 'Description']);
+
+  slots.forEach(style => {
+    table.addRow([
+      style.name === '' ? '' : `\`"${style.name}"\``,
+      style.docs
+    ]);
+  });
+
+  content.push(...table.toMarkdown());
+  content.push(``);
+  content.push(``);
+
+  return content;
+}

src/declarations/docs.ts

@@ -28,6 +28,7 @@ export interface JsonDocsComponent {
   methods: JsonDocsMethod[];
   events: JsonDocsEvent[];
   styles: JsonDocsStyle[];
+  slots: JsonDocsSlot[];
 }
 
 export interface JsonDocsTags {
@@ -91,3 +92,8 @@ export interface JsonDocsStyle {
   docs: string;
   annotation: string;
 }
+
+export interface JsonDocsSlot {
+  name: string;
+  docs: string;
+}