feat: add description section classes-mixins

Author: oscarmarina

packages/to-markdown/README.md

@@ -27,6 +27,7 @@ fs.writeFileSync('./custom-elements.md', markdown);
 | Option             | Type                         | Default | Description |
 | -------------      | ---------------------------- | ------- | ----------- |
 | headingOffset      | Integer                      | 0       | Offset the heading level by this number |
+| mainDescription    | Boolean                      | true    | Show description field for Class and Mixins |
 | private            | `'all'\|'details'\|'hidden'` | `'all'` | See [Private Members](#private-members) |
 | omitDeclarations   | `OptionalDeclarations[]`     | []      | See [Omit Declarations](#omit-declarations) |
 | omitSections       | `OptionalSections[]`         | []      | See [Omit Sections](#omit-sections) |
@@ -62,6 +63,7 @@ customElementsManifestToMarkdown(manifest, {
 The `omitSections` option is a `string[]` that controls which sections of a declaration's full entry in the manifest.json should be rendered in the final markdown output. The section names are:
 
 - mainHeading : "main-heading"
+- mainDescription : "main-description"
 - superClass : "super-class"
 - fields : "fields"
 - methods : "methods"
@@ -117,6 +119,7 @@ customElementsManifestToMarkdown(manifest, {
       "declarations": [
         {
           "kind": "class",
+          "description": "My description",
           "name": "SuperClass",
           "events": [
             {
@@ -420,6 +423,8 @@ customElementsManifestToMarkdown(manifest, {
 
 <details><summary>Result</summary>
 
+  My description
+
   ## `./fixtures/-TEST/package/my-element.js`:
 
   ### class: `SuperClass`

packages/to-markdown/fixtures/heading-offset-2/EXPECTED.md

@@ -1,3 +1,5 @@
+Large description of ...
+
 ### `my-element.js`:
 
 #### class: `MyElement`, `my-element`

packages/to-markdown/fixtures/heading-offset-2/README.md

@@ -1,3 +1,6 @@
+Large description of ...
+
+
 ### `my-element.js`:
 
 #### class: `MyElement`, `my-element`

packages/to-markdown/fixtures/heading-offset-2/custom-elements.json

@@ -9,6 +9,7 @@
         {
           "kind": "class",
           "name": "MyElement",
+          "description": "Large description of ...",
           "cssProperties": [
             {
               "name": "--background-color",

packages/to-markdown/index.js

@@ -22,6 +22,7 @@ const DECLARATIONS = {
 };
 
 const SECTIONS = {
+  mainDescription : 'main-description',
   mainHeading: 'main-heading',
   superClass: 'super-class',
   fields: 'fields', 
@@ -180,7 +181,20 @@ function makeModuleDoc(mod, options) {
   const variablesDecl = filteredDeclarations(declarations, omittedDeclarations, classNameFilter).filter(kindIs('variable'));
   const functionsDecl = filteredDeclarations(declarations, omittedDeclarations, classNameFilter).filter(kindIs('function'));
 
+  const mainDescription =
+    optionEnabled(omittedSections.mainDescription)
+      ? declarations.map((decl) =>{
+        if (['mixin', 'class'].includes(decl.kind) && decl.description) {
+          return html(`${decl.description}\n`);
+        } else {
+          return '';
+        }
+      })
+      : [];
+
   return [
+    ...mainDescription,
+
     optionEnabled(omittedSections.mainHeading) ? heading(1 + headingOffset, [inlineCode(mod.path), text(':')]) : null,
 
     ...(filteredDeclarations(declarations, omittedDeclarations, classNameFilter).flatMap(decl => {

packages/to-markdown/lib/cells.js

@@ -16,8 +16,11 @@ function getExportKind(x, options) {
     return x.kind ? inlineCode(x.kind) : text('');
 }
 
+const formatInline = x =>
+  x?.replace(/\n/g, '');
+
 export const DECLARATION = { heading: 'Declaration',     get: x => x.declaration?.name ?? '' };
-export const DEFAULT     = { heading: 'Default',         get: x => x.default, cellType: inlineCode };
+export const DEFAULT     = { heading: 'Default',         get: x => formatInline(x.default), cellType: inlineCode };
 export const NAME        = { heading: 'Name',            get: x => x.name, cellType: inlineCode };
 export const ATTR_FIELD  = { heading: 'Field',           get: x => x.fieldName };
 export const INHERITANCE = { heading: 'Inherited From',  get: x => x.inheritedFrom?.name ?? '' };

packages/to-markdown/package.json

@@ -59,5 +59,9 @@
     "remark-gfm": "^1.0.0",
     "remark-stringify": "^9.0.1",
     "unified": "^9.2.1"
+  },
+  "devDependencies": {
+    "@asdgf/cli": "https://gitpkg.now.sh/thepassle/asdgf/packages/cli?master",
+    "esbuild": "^0.19.2"
   }
 }

packages/to-markdown/test/to-markdown.test.js

@@ -27,7 +27,7 @@ const MAIN_TEST_CASE_OPTIONS = {
 };
 
 const OUTPUT_OPTIONS_TESTS_OPTIONS = {
-  'no-heading': { omitSections: ['main-heading'] },
+  'no-heading': { omitSections: ['main-heading','main-description'] },
   'class-name-filter': { classNameFilter: 'My*' },
   'no-attributes': { omitSections: ['attributes'] },
   'no-cssparts': { omitSections: ['css-parts'] },

packages/to-markdown/types/main.d.ts

@@ -9,6 +9,7 @@ enum Declarations {
 }
 
 enum Sections {
+  mainDescription = 'main-description',
   mainHeading = 'main-heading',
   superClass = 'super-class',
   fields = 'fields', 
@@ -29,6 +30,7 @@ type OptionalSections = `${Sections}`;
 export interface Options {
   private?: 'details'|'hidden'|'all';
   headingOffset?: number;
+  mainDescription?: boolean;
   omitSections: OptionalSections[];
   omitDeclarations: OptionalDeclarations[];
   classNameFilter: string | (() => string);