diff --git a/.editorconfig b/.editorconfig new file mode 100644 index 0000000..9e733f6 --- /dev/null +++ b/.editorconfig @@ -0,0 +1,31 @@ +root = true + +[*] +charset = utf-8 +indent_style = space +indent_size = 2 +end_of_line = lf +insert_final_newline = true +trim_trailing_whitespace = true + +[*.php] +indent_style = tab +indent_size = 4 + +[*.py] +charset = utf-8 +indent_style = space +indent_size = 4 +end_of_line = lf +insert_final_newline = true +trim_trailing_whitespace = true + +[Makefile] +indent_style = tab +indent_size = 4 + +[*.sln] +indent_style = tab + +[*.{md,mdx}] +trim_trailing_whitespace = false diff --git a/.eslintrc.js b/.eslintrc.js new file mode 100644 index 0000000..f3b4ca1 --- /dev/null +++ b/.eslintrc.js @@ -0,0 +1,11 @@ +module.exports = { + parser: '@typescript-eslint/parser', + extends: ['plugin:@typescript-eslint/recommended', 'prettier'], + parserOptions: { + sourceType: 'module', + }, + rules: { + 'prettier/prettier': 'error', + }, + plugins: ['@typescript-eslint', 'prettier'], +} diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml new file mode 100644 index 0000000..a428e06 --- /dev/null +++ b/.github/workflows/publish.yml @@ -0,0 +1,24 @@ +name: Publish + +on: + release: + types: [created] + +jobs: + build: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v2 + - name: Setup .npmrc file to publish to npm + uses: actions/setup-node@v1 + with: + node-version: '12.x' + registry-url: 'https://registry.npmjs.org' + - name: Install modules + run: npm install + - name: Build + run: npm run build + - name: Publish to npm + run: npm publish --access public + env: + NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }} diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..fb3ca3e --- /dev/null +++ b/.gitignore @@ -0,0 +1,117 @@ + +# Logs +logs +*.log +npm-debug.log* +yarn-debug.log* +yarn-error.log* +lerna-debug.log* + +# Diagnostic reports (https://nodejs.org/api/report.html) +report.[0-9]*.[0-9]*.[0-9]*.[0-9]*.json + +# Runtime data +pids +*.pid +*.seed +*.pid.lock + +# Directory for instrumented libs generated by jscoverage/JSCover +lib-cov + +# Coverage directory used by tools like istanbul +coverage +*.lcov + +# nyc test coverage +.nyc_output + +# Grunt intermediate storage (https://gruntjs.com/creating-plugins#storing-task-files) +.grunt + +# Bower dependency directory (https://bower.io/) +bower_components + +# node-waf configuration +.lock-wscript + +# Compiled binary addons (https://nodejs.org/api/addons.html) +build/Release + +# Dependency directories +node_modules/ +jspm_packages/ + +# Snowpack dependency directory (https://snowpack.dev/) +web_modules/ + +# TypeScript cache +*.tsbuildinfo + +# Optional npm cache directory +.npm + +# Optional eslint cache +.eslintcache + +# Microbundle cache +.rpt2_cache/ +.rts2_cache_cjs/ +.rts2_cache_es/ +.rts2_cache_umd/ + +# Optional REPL history +.node_repl_history + +# Output of 'npm pack' +*.tgz + +# Yarn Integrity file +.yarn-integrity + +# dotenv environment variables file +.env +.env.test + +# parcel-bundler cache (https://parceljs.org/) +.cache +.parcel-cache + +# Next.js build output +.next +out + +# Nuxt.js build / generate output +.nuxt +dist + +# Gatsby files +.cache/ +# Comment in the public line in if your project uses Gatsby and not Next.js +# https://nextjs.org/blog/next-9-1#public-directory-support +# public + +# vuepress build output +.vuepress/dist + +# Serverless directories +.serverless/ + +# FuseBox cache +.fusebox/ + +# DynamoDB Local files +.dynamodb/ + +# TernJS port file +.tern-port + +# Stores VSCode versions used for testing VSCode extensions +.vscode-test + +# yarn v2 +.yarn/cache +.yarn/unplugged +.yarn/build-state.yml +.yarn/install-state.gz +.pnp.* diff --git a/.prettierrc.js b/.prettierrc.js new file mode 100644 index 0000000..fec61a2 --- /dev/null +++ b/.prettierrc.js @@ -0,0 +1,7 @@ +module.exports = { + semi: false, + singleQuote: true, + trailingComma: 'es5', + arrowParens: 'always', + printWidth: 80, +} diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..0e259d4 --- /dev/null +++ b/LICENSE @@ -0,0 +1,121 @@ +Creative Commons Legal Code + +CC0 1.0 Universal + + CREATIVE COMMONS CORPORATION IS NOT A LAW FIRM AND DOES NOT PROVIDE + LEGAL SERVICES. DISTRIBUTION OF THIS DOCUMENT DOES NOT CREATE AN + ATTORNEY-CLIENT RELATIONSHIP. CREATIVE COMMONS PROVIDES THIS + INFORMATION ON AN "AS-IS" BASIS. CREATIVE COMMONS MAKES NO WARRANTIES + REGARDING THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS + PROVIDED HEREUNDER, AND DISCLAIMS LIABILITY FOR DAMAGES RESULTING FROM + THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS PROVIDED + HEREUNDER. + +Statement of Purpose + +The laws of most jurisdictions throughout the world automatically confer +exclusive Copyright and Related Rights (defined below) upon the creator +and subsequent owner(s) (each and all, an "owner") of an original work of +authorship and/or a database (each, a "Work"). + +Certain owners wish to permanently relinquish those rights to a Work for +the purpose of contributing to a commons of creative, cultural and +scientific works ("Commons") that the public can reliably and without fear +of later claims of infringement build upon, modify, incorporate in other +works, reuse and redistribute as freely as possible in any form whatsoever +and for any purposes, including without limitation commercial purposes. +These owners may contribute to the Commons to promote the ideal of a free +culture and the further production of creative, cultural and scientific +works, or to gain reputation or greater distribution for their Work in +part through the use and efforts of others. + +For these and/or other purposes and motivations, and without any +expectation of additional consideration or compensation, the person +associating CC0 with a Work (the "Affirmer"), to the extent that he or she +is an owner of Copyright and Related Rights in the Work, voluntarily +elects to apply CC0 to the Work and publicly distribute the Work under its +terms, with knowledge of his or her Copyright and Related Rights in the +Work and the meaning and intended legal effect of CC0 on those rights. + +1. Copyright and Related Rights. A Work made available under CC0 may be +protected by copyright and related or neighboring rights ("Copyright and +Related Rights"). Copyright and Related Rights include, but are not +limited to, the following: + + i. the right to reproduce, adapt, distribute, perform, display, + communicate, and translate a Work; + ii. moral rights retained by the original author(s) and/or performer(s); +iii. publicity and privacy rights pertaining to a person's image or + likeness depicted in a Work; + iv. rights protecting against unfair competition in regards to a Work, + subject to the limitations in paragraph 4(a), below; + v. rights protecting the extraction, dissemination, use and reuse of data + in a Work; + vi. database rights (such as those arising under Directive 96/9/EC of the + European Parliament and of the Council of 11 March 1996 on the legal + protection of databases, and under any national implementation + thereof, including any amended or successor version of such + directive); and +vii. other similar, equivalent or corresponding rights throughout the + world based on applicable law or treaty, and any national + implementations thereof. + +2. Waiver. To the greatest extent permitted by, but not in contravention +of, applicable law, Affirmer hereby overtly, fully, permanently, +irrevocably and unconditionally waives, abandons, and surrenders all of +Affirmer's Copyright and Related Rights and associated claims and causes +of action, whether now known or unknown (including existing as well as +future claims and causes of action), in the Work (i) in all territories +worldwide, (ii) for the maximum duration provided by applicable law or +treaty (including future time extensions), (iii) in any current or future +medium and for any number of copies, and (iv) for any purpose whatsoever, +including without limitation commercial, advertising or promotional +purposes (the "Waiver"). Affirmer makes the Waiver for the benefit of each +member of the public at large and to the detriment of Affirmer's heirs and +successors, fully intending that such Waiver shall not be subject to +revocation, rescission, cancellation, termination, or any other legal or +equitable action to disrupt the quiet enjoyment of the Work by the public +as contemplated by Affirmer's express Statement of Purpose. + +3. Public License Fallback. Should any part of the Waiver for any reason +be judged legally invalid or ineffective under applicable law, then the +Waiver shall be preserved to the maximum extent permitted taking into +account Affirmer's express Statement of Purpose. In addition, to the +extent the Waiver is so judged Affirmer hereby grants to each affected +person a royalty-free, non transferable, non sublicensable, non exclusive, +irrevocable and unconditional license to exercise Affirmer's Copyright and +Related Rights in the Work (i) in all territories worldwide, (ii) for the +maximum duration provided by applicable law or treaty (including future +time extensions), (iii) in any current or future medium and for any number +of copies, and (iv) for any purpose whatsoever, including without +limitation commercial, advertising or promotional purposes (the +"License"). The License shall be deemed effective as of the date CC0 was +applied by Affirmer to the Work. Should any part of the License for any +reason be judged legally invalid or ineffective under applicable law, such +partial invalidity or ineffectiveness shall not invalidate the remainder +of the License, and in such case Affirmer hereby affirms that he or she +will not (i) exercise any of his or her remaining Copyright and Related +Rights in the Work or (ii) assert any associated claims and causes of +action with respect to the Work, in either case contrary to Affirmer's +express Statement of Purpose. + +4. Limitations and Disclaimers. + + a. No trademark or patent rights held by Affirmer are waived, abandoned, + surrendered, licensed or otherwise affected by this document. + b. Affirmer offers the Work as-is and makes no representations or + warranties of any kind concerning the Work, express, implied, + statutory or otherwise, including without limitation warranties of + title, merchantability, fitness for a particular purpose, non + infringement, or the absence of latent or other defects, accuracy, or + the present or absence of errors, whether or not discoverable, all to + the greatest extent permissible under applicable law. + c. Affirmer disclaims responsibility for clearing rights of other persons + that may apply to the Work or any use thereof, including without + limitation any person's Copyright and Related Rights in the Work. + Further, Affirmer disclaims responsibility for obtaining any necessary + consents, permissions or other rights required for any use of the + Work. + d. Affirmer understands and acknowledges that Creative Commons is not a + party to this document and has no duty or obligation with respect to + this CC0 or use of the Work. diff --git a/README.md b/README.md new file mode 100644 index 0000000..1d0b549 --- /dev/null +++ b/README.md @@ -0,0 +1,66 @@ +# typedoc-plugin-not-exported + +[![npm package](https://img.shields.io/badge/npm%20i-example--typescript--package-brightgreen)](https://www.npmjs.com/package/typedoc-plugin-not-exported) [![version number](https://img.shields.io/npm/v/typedoc-plugin-not-exported?color=green&label=version)](https://github.com/tomchen/typedoc-plugin-not-exported/releases) [![License](https://img.shields.io/github/license/tomchen/typedoc-plugin-not-exported)](https://github.com/tomchen/typedoc-plugin-not-exported/blob/main/LICENSE) + +This typedoc plugin can force inclusion of specific symbols (variables) that are not exported, by making them fake exports. + +Install the plugin: + +```bash +npm i typedoc-plugin-not-exported +``` + +In your code, tag the symbols (variables / types / interfaces / classes etc.) that are not exported but you still want to include in the generated documentation. + +The default tag is `@notExported`. + +Example 1: + +```ts +/** + * My class + * @notExported + */ +class Cls { + convert(str: string): string { + return str + } +} +export const me = new Cls() +``` + +Example 2: + +```ts +/** + * @notExported + */ +type twoNumbers = [number, number] +/** + * @notExported + */ +type threeNumbers = [number, number, number] + +export type twoOrThreeNumbers = twoNumbers | threeNumbers +export function sum2(ns: twoOrThreeNumbers): number { + return ns.reduce((a, b) => a + b) +} +``` + +Then use the command as usual: + +```bash +typedoc src/index.ts +``` + +Or, if you are using `@internalDoNotUse` tag instead of `@notExported`, run: + +```bash +typedoc --includeTag internalDoNotUse src/index.ts +``` + +That's it. + +Originally from [here](https://github.com/TypeStrong/typedoc/issues/1474#issuecomment-766178261). [CC0](LICENSE). + +**Keywords: typedoc plugin force include non exported unexported variable symbol fake export option flag tag mode file exclude inclusion internal external** diff --git a/package.json b/package.json new file mode 100644 index 0000000..8d4aac1 --- /dev/null +++ b/package.json @@ -0,0 +1,38 @@ +{ + "name": "typedoc-plugin-not-exported", + "version": "0.1.0", + "description": "TypeDoc plugin that forces inclusion of non-exported symbols (variables)", + "main": "src/main.js", + "scripts": {}, + "files": [ + "src" + ], + "keywords": [ + "typedocplugin", + "typedoc", + "plugin", + "exported", + "nonexported", + "include", + "plugin" + ], + "author": "Tom Chen ", + "license": "CC0", + "homepage": "https://github.com/tomchen/typedoc-plugin-not-exported", + "repository": { + "type": "git", + "url": "git@github.com:tomchen/typedoc-plugin-not-exported.git" + }, + "bugs": { + "url": "https://github.com/tomchen/typedoc-plugin-not-exported/issues" + }, + "peerDependencies": { + "typedoc": ">=0.20.0" + }, + "devDependencies": { + "eslint": "^7.18.0", + "eslint-config-prettier": "^7.2.0", + "eslint-plugin-prettier": "^3.3.1", + "prettier": "^2.2.1" + } +} diff --git a/src/main.js b/src/main.js new file mode 100644 index 0000000..52e9e2b --- /dev/null +++ b/src/main.js @@ -0,0 +1,80 @@ +/** + * typedoc-plugin-not-exported + * TypeDoc plugin that forces inclusion of non-exported symbols (variables) + * Originally from https://github.com/TypeStrong/typedoc/issues/1474#issuecomment-766178261 + * https://github.com/tomchen/typedoc-plugin-not-exported + * CC0 + */ + +//@ts-check + +const { Converter, TypeScript } = require('typedoc') // version 0.20.x + +const ModuleFlags = + TypeScript.SymbolFlags.ValueModule | TypeScript.SymbolFlags.NamespaceModule + +/** @param {{ application: import("typedoc").Application }} param0 */ +exports.load = function ({ application }) { + let includeTag = 'notExported' + + application.options.addDeclaration({ + name: 'includeTag', + help: + '[typedoc-plugin-not-exported] Specify the tag name for non-exported member to be imported under', + defaultValue: includeTag, + }) + + application.converter.on(Converter.EVENT_BEGIN, () => { + includeTag = application.options.getValue('includeTag').toLocaleLowerCase() + }) + + application.converter.on( + Converter.EVENT_CREATE_DECLARATION, + lookForFakeExports + ) + + /** + * @param {import("typedoc/dist/lib/converter/context").Context} context + * @param {import("typedoc").DeclarationReflection} _reflection + * @param {TypeScript.Node | undefined} node + */ + function lookForFakeExports(context, _reflection, node) { + if (!node) { + return + } + + /** @type {TypeScript.Symbol | undefined} */ + const moduleSymbolTemp = context.checker.getSymbolAtLocation(node) + const moduleSymbol = + moduleSymbolTemp !== null && moduleSymbolTemp !== undefined + ? moduleSymbolTemp + : /** @type {any} */ node.symbol + + if (!moduleSymbol) { + // Global file, no point in doing anything here. TypeDoc will already + // include everything declared in this file. + return + } + + // Make sure we are allowed to call getExportsOfModule + if ((moduleSymbol.flags & ModuleFlags) === 0) { + return + } + + const exportedSymbols = context.checker.getExportsOfModule(moduleSymbol) + + const symbols = context.checker + .getSymbolsInScope(node, TypeScript.SymbolFlags.ModuleMember) + .filter((symbol) => !exportedSymbols.includes(symbol)) + + for (const symbol of symbols) { + if ( + symbol + .getJsDocTags() + .some((tag) => tag.name.toLocaleLowerCase() === includeTag) + ) { + context.converter.convertSymbol(context, symbol) + } + } + } +}