diff --git a/.github/dependabot.yml b/.github/dependabot.yml index e0ad046de..bb236c12d 100644 --- a/.github/dependabot.yml +++ b/.github/dependabot.yml @@ -1,7 +1,7 @@ # To get started with Dependabot version updates, you'll need to specify which # package ecosystems to update and where the package manifests are located. # Please see the documentation for all configuration options: -# https://help.github.com/github/administering-a-repository/configuration-options-for-dependency-updates +# https://docs.github.com/en/code-security/dependabot version: 2 updates: diff --git a/.github/workflows/codeql.yml b/.github/workflows/codeql.yml new file mode 100644 index 000000000..db650acb4 --- /dev/null +++ b/.github/workflows/codeql.yml @@ -0,0 +1,41 @@ +name: "CodeQL" + +on: + push: + branches: [ "master" ] + pull_request: + branches: [ "master" ] + schedule: + - cron: '0 0 1 * *' + workflow_dispatch: + +jobs: + analyze: + name: Analyze + runs-on: ubuntu-latest + permissions: + security-events: write + + strategy: + fail-fast: false + matrix: + language: [ 'javascript-typescript' ] + + steps: + - name: Checkout repository + uses: actions/checkout@v4 + + # Initializes the CodeQL tools for scanning. + - name: Initialize CodeQL + uses: github/codeql-action/init@v3 + with: + languages: ${{ matrix.language }} + queries: +security-and-quality + + - name: Autobuild + uses: github/codeql-action/autobuild@v3 + + - name: Perform CodeQL Analysis + uses: github/codeql-action/analyze@v3 + with: + category: "/language:${{matrix.language}}" diff --git a/.github/workflows/node.js.yml b/.github/workflows/node.js.yml index 936d5100a..2d8e7a62f 100644 --- a/.github/workflows/node.js.yml +++ b/.github/workflows/node.js.yml @@ -5,26 +5,25 @@ name: Node.js CI on: push: - branches: [ master ] + branches: [master] pull_request: - branches: [ master ] + branches: [master] jobs: build: - runs-on: ubuntu-latest strategy: matrix: - node-version: [14.x, 16.x, 18.x] + node-version: [18.x, 20.x] # See supported Node.js release schedule at https://nodejs.org/en/about/releases/ steps: - - uses: actions/checkout@v3 - - name: Use Node.js ${{ matrix.node-version }} - uses: actions/setup-node@v3.4.1 - with: - node-version: ${{ matrix.node-version }} - cache: 'npm' - - run: npm ci - - run: npm run test-ci + - uses: actions/checkout@v4 + - name: Use Node.js ${{ matrix.node-version }} + uses: actions/setup-node@v4 + with: + node-version: ${{ matrix.node-version }} + cache: 'npm' + - run: npm ci + - run: npm run test-ci diff --git a/CHANGELOG.md b/CHANGELOG.md index 180e2136c..dd16f8756 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,26 @@ All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines. +### [14.0.3](https://github.com/documentationjs/documentation/compare/v14.0.1...v14.0.3) (2024-01-30) + + +### Bug Fixes + +* **exported:** respect `parse-extension` & `require-extension` ([#1484](https://github.com/documentationjs/documentation/issues/1484)) ([798fa10](https://github.com/documentationjs/documentation/commit/798fa10595d7523032ac187ae9c8aa943c15e8da)), closes [#1272](https://github.com/documentationjs/documentation/issues/1272) [#1258](https://github.com/documentationjs/documentation/issues/1258) +* fix GFM markdown output ([#1553](https://github.com/documentationjs/documentation/issues/1553)) ([1cc2f98](https://github.com/documentationjs/documentation/commit/1cc2f984315fc5aaf898c64d8e1eb2b4e70cd482)) + +### [14.0.2](https://github.com/documentationjs/documentation/compare/v14.0.1...v14.0.2) (2023-05-19) + + +### Bug Fixes + +* **exported:** respect `parse-extension` & `require-extension` ([#1484](https://github.com/documentationjs/documentation/issues/1484)) ([798fa10](https://github.com/documentationjs/documentation/commit/798fa10595d7523032ac187ae9c8aa943c15e8da)), closes [#1272](https://github.com/documentationjs/documentation/issues/1272) [#1258](https://github.com/documentationjs/documentation/issues/1258) + +## [14.0.1](https://github.com/documentationjs/documentation/compare/v14.0.0...v14.0.1) (2022-12-14) + +### Improvements +* chore: upgrade git-url-parse to 13.1.0 to fix vulnerabilities [#1565](https://github.com/documentationjs/documentation/pull/1565) + ## [14.0.0](https://github.com/documentationjs/documentation/compare/v14.0.0-alpha.1...v14.0.0) (2022-08-19) ## [14.0.0-alpha.1](https://github.com/documentationjs/documentation/compare/v14.0.0-alpha.0...v14.0.0-alpha.1) (2022-08-07) @@ -16,13 +36,13 @@ All notable changes to this project will be documented in this file. See [standa ### ⚠ BREAKING CHANGES -* all Extensions whould contains '.' so that mean if you have just 'ts' then need to convert to '.ts' +* all Extensions should contains '.' so that mean if you have just 'ts' then need to convert to '.ts' * external parameter was removed Migration plan propose to move all external resources to input usages Motivation: packages has many inputs which describe in package.json -so that mean need each time to parse all package.json of exsternal resources to understand which etry point need to pick. -But it is base on guesses because entry point may could not contains a documentation and the best way to handle it manualy. -* The serve parametr was remove, you can use any other tools which could be refresh and store your html site +so that mean need each time to parse all package.json of external resources to understand which entry point need to pick. +But it is base on guesses because entry point may could not contains a documentation and the best way to handle it manually. +* The serve parameter was removed, you can use any other tools which could be refresh and store your html site The private parameter has removed, use a access * documentation.js will now require node 14 or later. @@ -62,7 +82,7 @@ The private parameter has removed, use a access ### Bug Fixes -* [@see](https://github.com/see) tags incorrectly formatted in markdown ouput fixed [#1337](https://github.com/documentationjs/documentation/issues/1337) ([5d8d450](https://github.com/documentationjs/documentation/commit/5d8d4504d52a5bb0a0432bf399bbd82d9e5ea7fc)) +* [@see](https://github.com/see) tags incorrectly formatted in markdown output fixed [#1337](https://github.com/documentationjs/documentation/issues/1337) ([5d8d450](https://github.com/documentationjs/documentation/commit/5d8d4504d52a5bb0a0432bf399bbd82d9e5ea7fc)) ### [13.2.1](https://github.com/documentationjs/documentation/compare/v13.2.0...v13.2.1) (2021-04-06) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1938ba710..2169a477e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -39,6 +39,6 @@ Release process: * Confirm that `master` passes CI tests * Run `npm run release` or in case it's a prerelease you'd run i.e. `npm run release -- --prerelease alpha` - * It will automatically update teh version in package.json and make a git tag. + * It will automatically update the version in package.json and make a git tag. * Push commits * npm publish diff --git a/LICENSE b/LICENSE index 09a06361e..4a5ddc55b 100644 --- a/LICENSE +++ b/LICENSE @@ -1,6 +1,6 @@ ISC License -Copyright (c) 2015, documentationjs <> +Copyright (c) 2025, documentationjs <> Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above diff --git a/README.md b/README.md index 9eb477b54..90f636934 100644 --- a/README.md +++ b/README.md @@ -9,7 +9,6 @@ [![Circle CI](https://circleci.com/gh/documentationjs/documentation/tree/master.svg?style=shield)](https://circleci.com/gh/documentationjs/documentation/tree/master) [![npm version](https://badge.fury.io/js/documentation.svg)](http://badge.fury.io/js/documentation) [![Gitter](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/documentationjs/documentation?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge) -[![David](https://david-dm.org/documentationjs/documentation.svg)](https://david-dm.org/documentationjs/documentation) [![Inline docs](http://inch-ci.org/github/documentationjs/documentation.svg?branch=master&style=flat-square)](http://inch-ci.org/github/documentationjs/documentation) [:date: Current maintenance status](https://github.com/documentationjs/documentation/wiki/Current-maintenance-status) diff --git a/__tests__/__snapshots__/bin.js.snap b/__tests__/__snapshots__/bin.js.snap index c060e2a3c..ca6d4bbb8 100644 --- a/__tests__/__snapshots__/bin.js.snap +++ b/__tests__/__snapshots__/bin.js.snap @@ -2168,6 +2168,304 @@ f5 comment " `; +exports[`build GFM (e.g. markdown tables) for -f md 1`] = ` +" + +### Table of Contents + +* [Klass][1] + * [Parameters][2] + * [getFoo][3] + * [Examples][4] + * [withOptions][5] + * [Parameters][6] + * [withDeepOptions][7] + * [Parameters][8] + * [isClass][9] + * [Parameters][10] + * [isWeird][11] + * [Parameters][12] + * [isBuffer][13] + * [Parameters][14] + * [isArrayOfBuffers][15] + * [Parameters][16] + * [Examples][17] + * [MAGIC\\\\_NUMBER][18] + * [event][19] +* [CustomError][20] + * [Properties][21] +* [bar][22] +* [bar2][23] + * [Parameters][24] +* [bar3][25] +* [Foo][26] + * [bar][27] +* [Foobar][28] + * [bar][29] +* [customStreams][30] + * [passthrough][31] +* [tableObj][32] + +## Klass + +**Extends Stream.Writable** + +Creates a new Klass + +### Parameters + +* \`foo\` + +### getFoo + +Get this Klass's foo + +#### Examples + +this shows you how to getFoo + +\`\`\`javascript +var x = foo.getFoo(); +\`\`\` + +Returns **[Number][33]** foo + +### withOptions + +A function with an options parameter + +#### Parameters + +* \`options\` **[Object][34]** + + * \`options.foo\` **[string][35]** + * \`options.bar\` **[number][33]** +* \`otherOptions\` **[number][33]?** + +### withDeepOptions + +A function with a deep options parameter + +#### Parameters + +* \`options\` **[Object][34]** + + * \`options.foo\` **[string][35]** + * \`options.bar\` **[Object][34]** + + * \`options.bar.buz\` **[string][35]** + +### isClass + +Decide whether an object is a Klass instance +This is a \\\\[klasssic][Klass][1] +This is a \\\\[link to something that does not exist][DoesNot][36] + +#### Parameters + +* \`other\` **[Object][34]** +* \`also\` **any** + +Returns **[boolean][37]** whether the other thing is a Klass + +### isWeird + +A function that triggers the case where the autolinker doesn't find +the referenced class type + +#### Parameters + +* \`other\` **Weird** + +Returns **[boolean][37]** whether the other thing is a Klass + +### isBuffer + +This method takes a Buffer object that will be linked to nodejs.org + +#### Parameters + +* \`buf\` **([Buffer][38] | [string][35])** +* \`size\` **[number][33]** size (optional, default \`0\`) + +Returns **[boolean][37]** whether the other thing is a Klass + +### isArrayOfBuffers + +This method takes an array of buffers and counts them + +#### Parameters + +* \`buffers\` **[Array][39]<[Buffer][38]>** some buffers + +#### Examples + +\`\`\`javascript +var k = new Klass(); +k.isArrayOfBuffers(); +\`\`\` + +Returns **[number][33]** how many + +### MAGIC\\\\_NUMBER + +A magic number that identifies this Klass. + +### event + +Klass event + +## CustomError + +a typedef with nested properties + +### Properties + +* \`error\` **[object][34]** An error + + * \`error.code\` **[string][35]** The error's code + * \`error.description\` **[string][35]** The error's description + +## bar + +Get an instance of [Klass][1]. Will make +a [klass instance multiword][1], +like a [klass][1] + +Returns **[Klass][1]** that class + +## bar2 + +Rest property function + +### Parameters + +* \`toys\` **...[Number][33]** + +Returns **[undefined][40]** nothing + +## bar3 + +Get an instance of [Klass][1]. Will make +a [klass instance multiword][1], +like a [klass][1]. This needs a [number][33] input. + +Returns **[undefined][40]** nothing + +## Foo + +This is Foo + +### bar + +This is bar + +## Foobar + +This is Foobar +must have a distinct id from Foo.bar + +### bar + +This is bar + +## customStreams + +I am the container of stream types + +### passthrough + +I am a passthrough stream that belongs to customStreams + +## tableObj + +| Col 1 | Col 2 | Col 3 | +| ----- | ----- | ----- | +| Dat 1 | Dat 2 | Dat 3 | +| Dat 4 | Dat 5 | Dat 6 | + +[1]: #klass + +[2]: #parameters + +[3]: #getfoo + +[4]: #examples + +[5]: #withoptions + +[6]: #parameters-1 + +[7]: #withdeepoptions + +[8]: #parameters-2 + +[9]: #isclass + +[10]: #parameters-3 + +[11]: #isweird + +[12]: #parameters-4 + +[13]: #isbuffer + +[14]: #parameters-5 + +[15]: #isarrayofbuffers + +[16]: #parameters-6 + +[17]: #examples-1 + +[18]: #magic_number + +[19]: #event + +[20]: #customerror + +[21]: #properties + +[22]: #bar + +[23]: #bar2 + +[24]: #parameters-7 + +[25]: #bar3 + +[26]: #foo + +[27]: #bar-1 + +[28]: #foobar + +[29]: #bar-2 + +[30]: #customstreams + +[31]: #passthrough + +[32]: #tableobj + +[33]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number + +[34]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object + +[35]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String + +[36]: DoesNot + +[37]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean + +[38]: https://nodejs.org/api/buffer.html + +[39]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array + +[40]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/undefined +" +`; + exports[`lint command generates lint output 1`] = `""`; exports[`should use browser resolve 1`] = ` diff --git a/__tests__/bin.js b/__tests__/bin.js index 7f46bca1e..088d8755e 100644 --- a/__tests__/bin.js +++ b/__tests__/bin.js @@ -368,6 +368,21 @@ test.skip('fatal error', async function () { } }); +test('build GFM (e.g. markdown tables) for -f md', async function () { + const data = await documentation( + ['build', 'fixture/html/nested.input.js', '--shallow', '-f', 'md'], + {}, + false + ); + expect(data).toMatchSnapshot(); + expect(data).toMatch( + `| Col 1 | Col 2 | Col 3 | +| ----- | ----- | ----- | +| Dat 1 | Dat 2 | Dat 3 | +| Dat 4 | Dat 5 | Dat 6 |` + ); +}); + test.skip('build --document-exported', async function () { const data = await documentation( ['build fixture/document-exported.input.js --document-exported -f md'], diff --git a/__tests__/lib/__snapshots__/sort.js.snap b/__tests__/lib/__snapshots__/sort.js.snap index 13fa12e9b..f35e6bf19 100644 --- a/__tests__/lib/__snapshots__/sort.js.snap +++ b/__tests__/lib/__snapshots__/sort.js.snap @@ -139,7 +139,7 @@ Array [ "sortKey": "c", }, "kind": "function", - "memberof": "classB", + "memberof": "classA", "name": "bananas", }, Object { @@ -174,8 +174,36 @@ Array [ "sortKey": "c", }, "kind": "function", - "memberof": "classB", + "memberof": "classA", + "name": "bananas", + }, +] +`; + +exports[`sort toc with files absolute path 4`] = ` +Array [ + Object { + "context": Object { + "sortKey": "c", + }, + "kind": "function", + "memberof": "classA", "name": "bananas", }, + Object { + "context": Object { + "sortKey": "b", + }, + "memberof": "classB", + "name": "carrot", + }, + Object { + "context": Object { + "sortKey": "a", + }, + "kind": "function", + "memberof": "classB", + "name": "apples", + }, ] `; diff --git a/__tests__/lib/sort.js b/__tests__/lib/sort.js index 76ce57f3c..941b163b1 100644 --- a/__tests__/lib/sort.js +++ b/__tests__/lib/sort.js @@ -141,7 +141,7 @@ test('sort toc with files absolute path', function () { context: { sortKey: 'c' }, name: 'bananas', kind: 'function', - memberof: 'classB' + memberof: 'classA' }; const snowflake = { @@ -159,4 +159,10 @@ test('sort toc with files absolute path', function () { sortOrder: ['kind', 'alpha'] }) ).toMatchSnapshot(); + + expect( + sort([carrot, apples, bananas], { + sortOrder: ['memberof', 'kind', 'alpha'] + }) + ).toMatchSnapshot(); }); diff --git a/docs/GETTING_STARTED.md b/docs/GETTING_STARTED.md index 1fc98ffe8..c1b062c29 100644 --- a/docs/GETTING_STARTED.md +++ b/docs/GETTING_STARTED.md @@ -83,6 +83,17 @@ This is the syntax that describes an optional parameter: If an input is omitted, the default value of `5` will be passed to the function. +
+ +### **Show Options passing Value** + +```js + * @param {{status : "active" | "inactive" | "inprocess"}} +``` + +
+
+ ## What `documentation` does, so you don't have to `documentation` does some minor magic to auto-generate documentation. Unless diff --git a/docs/NODE_API.md b/docs/NODE_API.md index c5716e70b..f0f9d3dcc 100644 --- a/docs/NODE_API.md +++ b/docs/NODE_API.md @@ -72,7 +72,7 @@ comments, given a root file as a path. generated documentation. * `args.shallow` **[boolean][20]** whether to avoid dependency parsing even in JavaScript code. (optional, default `false`) - * `args.order` **[Array][17]<([string][18] | [Object][19])>** optional array that + * `args.sortOrder` **[Array][17]<([string][18] | [Object][19])>** optional array that defines sorting order of documentation (optional, default `[]`) * `args.access` **[Array][17]<[string][18]>** an array of access levels to output in documentation (optional, default `[]`) @@ -94,7 +94,8 @@ var documentation = require('documentation'); documentation.build(['index.js'], { // only output comments with an explicit @public tag - access: ['public'] + access: ['public'], + sortOrder: ['kind', 'alpha'] }).then(res => { // res is an array of parsed comments with inferred properties // and more: everything you need to build documentation or diff --git a/docs/THEMING.md b/docs/THEMING.md index cd9761c9f..a2d4a4b00 100644 --- a/docs/THEMING.md +++ b/docs/THEMING.md @@ -34,6 +34,7 @@ for some ideas. - You can now make changes that will show up when you generate your docs using your theme. Example `package.json` `scripts` entry: `"documentation build index.js -f html -o docs --theme node_modules/docjs-theme"` #### Changes to Default Theme Via documentation.yml + If a documentation.yml file is used to establish a table of contents for your documentation, small changes to the default style can be made via a