diff --git a/packages/to-markdown/README.md b/packages/to-markdown/README.md index 0bdae681..9c7bac59 100644 --- a/packages/to-markdown/README.md +++ b/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, {
Result + My description + ## `./fixtures/-TEST/package/my-element.js`: ### class: `SuperClass` diff --git a/packages/to-markdown/fixtures/heading-offset-2/EXPECTED.md b/packages/to-markdown/fixtures/heading-offset-2/EXPECTED.md index bca89257..055f175b 100644 --- a/packages/to-markdown/fixtures/heading-offset-2/EXPECTED.md +++ b/packages/to-markdown/fixtures/heading-offset-2/EXPECTED.md @@ -1,3 +1,5 @@ +Large description of ... + ### `my-element.js`: #### class: `MyElement`, `my-element` diff --git a/packages/to-markdown/fixtures/heading-offset-2/README.md b/packages/to-markdown/fixtures/heading-offset-2/README.md index bca89257..9a4bde9b 100644 --- a/packages/to-markdown/fixtures/heading-offset-2/README.md +++ b/packages/to-markdown/fixtures/heading-offset-2/README.md @@ -1,3 +1,6 @@ +Large description of ... + + ### `my-element.js`: #### class: `MyElement`, `my-element` diff --git a/packages/to-markdown/fixtures/heading-offset-2/custom-elements.json b/packages/to-markdown/fixtures/heading-offset-2/custom-elements.json index 1a643b6f..a036b226 100644 --- a/packages/to-markdown/fixtures/heading-offset-2/custom-elements.json +++ b/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", diff --git a/packages/to-markdown/index.js b/packages/to-markdown/index.js index 3971066c..2c5cf1d8 100644 --- a/packages/to-markdown/index.js +++ b/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 => { diff --git a/packages/to-markdown/lib/cells.js b/packages/to-markdown/lib/cells.js index cc8f720f..aa5e82fd 100644 --- a/packages/to-markdown/lib/cells.js +++ b/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 ?? '' }; diff --git a/packages/to-markdown/package.json b/packages/to-markdown/package.json index b9145817..f3db64f2 100644 --- a/packages/to-markdown/package.json +++ b/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" } } diff --git a/packages/to-markdown/test/to-markdown.test.js b/packages/to-markdown/test/to-markdown.test.js index 530f92f5..4eea4e34 100644 --- a/packages/to-markdown/test/to-markdown.test.js +++ b/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'] }, diff --git a/packages/to-markdown/types/main.d.ts b/packages/to-markdown/types/main.d.ts index 0ba757c4..9c3a74d4 100644 --- a/packages/to-markdown/types/main.d.ts +++ b/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);