{"_id":"@13ms/funky","_rev":"25-b4556ed3f2fd655d26c7188678240475","name":"@13ms/funky","dist-tags":{"latest":"1.0.1"},"versions":{"1.0.0":{"name":"@13ms/funky","version":"1.0.0","description":"A jsdoc plugin for quickly creating scoped and access tagged functions","type":"module","main":"dist/bundle.min.cjs","scripts":{"build":"npm run test && rollup --config ./config/rollup.config.js && npm run tokei","build-dev":"rollup --config ./config/rollup.config.js","docs":"jsdoc -c ./config/jsdoc.config.json","docs-sample":"jsdoc -c ./config/jsdoc-sample.config.json","serve-docs":"npm run docs && http-server ./jsdoc -o index.html","serve-docs-sample":"npm run docs-sample && http-server ./jsdoc-sample -o index.html","test":"jest","tokei":"node scripts/tokei.js","watch-docs":"npm run serve-docs & nodemon --watch ./src --ext js,css --exec 'npm run docs'","watch-docs-sample":"npm run serve-docs-sample & nodemon --watch ./src --ext js,css --exec 'npm run build-dev && npm run docs-sample'"},"repository":{"type":"git","url":"git+https://github.com/blameitonyourisp/funky.git"},"keywords":["jsdoc","plugin","scoped","funky"],"author":{"name":"James Reid"},"license":"MIT","bugs":{"url":"https://github.com/blameitonyourisp/funky/issues"},"homepage":"https://github.com/blameitonyourisp/funky#readme","dependencies":{"jsdoc":"^4.0.2"},"devDependencies":{"@babel/plugin-transform-modules-commonjs":"^7.21.2","@jest/globals":"^29.5.0","@rollup/plugin-terser":"^0.4.0","docdash":"^2.0.1","http-server":"^14.1.1","jest":"^29.5.0","nodemon":"^2.0.22","rollup":"^3.20.2"},"gitHead":"be5ebb2f45e9c783aea14e143567b3bc217a815e","_id":"@13ms/funky@1.0.0","_nodeVersion":"18.13.0","_npmVersion":"8.19.3","dist":{"integrity":"sha512-qEYfQmTFPF43drdIM7SbvS5pIQ0aJ2nez3XfjtuHOGJ0pbWAWxvZJeMp3BvuhgT/FxDWL7aHrAvR1J5ivmi0Mg==","shasum":"1129d309daee4ee9c8f7cfb2531516a44d7a72e8","tarball":"https://registry.npmjs.org/@13ms/funky/-/funky-1.0.0.tgz","fileCount":19,"unpackedSize":38553,"signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEUCIQDsdL/L5DFsDgIMxr6Gf14xPP76gsxC/VAM37kfQyI3RgIgJtGkPUprNBJM4PHfXuFoB3Wf9IyBvZZ1zHReMC0R8ss="}]},"_npmUser":{"name":"jimbob3806","email":"jamesreid3806@gmail.com"},"directories":{},"maintainers":[{"name":"jimbob3806","email":"jamesreid3806@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/funky_1.0.0_1687994149918_0.14961523772498664"},"_hasShrinkwrap":false},"1.0.1":{"name":"@13ms/funky","version":"1.0.1","description":"A jsdoc plugin for quickly creating scoped and access tagged functions","type":"module","main":"dist/bundle.min.cjs","scripts":{"build":"npm run test && rollup --config ./config/rollup.config.js && npm run tokei","build-dev":"rollup --config ./config/rollup.config.js","docs":"jsdoc -c ./config/jsdoc.config.json","docs-sample":"jsdoc -c ./config/jsdoc-sample.config.json","serve-docs":"npm run docs && http-server ./jsdoc -o index.html","serve-docs-sample":"npm run docs-sample && http-server ./jsdoc-sample -o index.html","test":"jest","tokei":"node scripts/tokei.js","watch-docs":"npm run serve-docs & nodemon --watch ./src --ext js,css --exec 'npm run docs'","watch-docs-sample":"npm run serve-docs-sample & nodemon --watch ./src --ext js,css --exec 'npm run build-dev && npm run docs-sample'"},"repository":{"type":"git","url":"git+https://github.com/blameitonyourisp/funky.git"},"keywords":["jsdoc","plugin","scoped","funky"],"author":{"name":"James Reid"},"license":"MIT","bugs":{"url":"https://github.com/blameitonyourisp/funky/issues"},"homepage":"https://github.com/blameitonyourisp/funky#readme","dependencies":{"jsdoc":"^4.0.2"},"devDependencies":{"@babel/plugin-transform-modules-commonjs":"^7.21.2","@jest/globals":"^29.5.0","@rollup/plugin-terser":"^0.4.0","docdash":"^2.0.1","http-server":"^14.1.1","jest":"^29.5.0","nodemon":"^2.0.22","rollup":"^3.20.2"},"gitHead":"76497422e490ed14cf2fbfefe8144c981d487877","_id":"@13ms/funky@1.0.1","_nodeVersion":"18.13.0","_npmVersion":"8.19.3","dist":{"integrity":"sha512-K6PznBYoqwKcWiEVPncWwOImsqlgzpQjYSPWCWfpZJjpNy+Zjutb7kIQ/c6u692apFG4ik2OsSapou3Oorc91Q==","shasum":"4395bff5d039a6cef0972b9f5b1fc5d509e8ae2b","tarball":"https://registry.npmjs.org/@13ms/funky/-/funky-1.0.1.tgz","fileCount":19,"unpackedSize":38893,"signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEUCIQD/ttmHpGQSrTo7qvjVDGXzeYqtHn0QHye48fA+MEAiAwIgMWubL0YSciQBeib7H22zApvJPGPPX3MenstYPIMY1XI="}]},"_npmUser":{"name":"jimbob3806","email":"jamesreid3806@gmail.com"},"directories":{},"maintainers":[{"name":"jimbob3806","email":"jamesreid3806@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/funky_1.0.1_1687995484069_0.8249426842547121"},"_hasShrinkwrap":false}},"time":{"created":"2023-03-27T17:56:42.728Z","0.0.1":"2023-03-27T17:56:43.064Z","modified":"2023-06-28T23:38:04.546Z","1.0.2":"2023-03-28T01:55:51.131Z","1.0.3":"2023-03-28T03:23:45.800Z","1.0.4":"2023-03-28T14:59:39.984Z","1.1.0":"2023-03-28T17:04:38.168Z","1.1.1":"2023-05-25T15:18:56.095Z","1.1.2":"2023-05-25T20:41:07.870Z","1.1.3":"2023-06-07T23:06:16.681Z","1.1.4":"2023-06-27T00:28:09.247Z","1.1.5":"2023-06-27T13:03:48.179Z","1.1.6":"2023-06-27T14:33:20.315Z","1.1.7":"2023-06-28T23:11:33.336Z","1.0.0":"2023-06-28T23:15:50.180Z","1.0.1":"2023-06-28T23:38:04.308Z"},"maintainers":[{"name":"jimbob3806","email":"jamesreid3806@gmail.com"}],"description":"A jsdoc plugin for quickly creating scoped and access tagged functions","homepage":"https://github.com/blameitonyourisp/funky#readme","keywords":["jsdoc","plugin","scoped","funky"],"repository":{"type":"git","url":"git+https://github.com/blameitonyourisp/funky.git"},"author":{"name":"James Reid"},"bugs":{"url":"https://github.com/blameitonyourisp/funky/issues"},"license":"MIT","readme":"

\n \n

\n\n# Funky\n\nA jsdoc plugin for quickly creating scoped and access tagged functions. This repository is hosted on [github](https://github.com), if you're already reading this there, then great! Otherwise browse the repository [here](https://github.com/blameitonyourisp/funky).\n\n![](https://img.shields.io/github/license/blameitonyourisp/funky?style=for-the-badge&labelColor=181b1a&color=779966) ![](https://img.shields.io/github/package-json/v/blameitonyourisp/funky/master?style=for-the-badge&labelColor=181b1a&color=779966) \n\n### Table of Contents\n\n- [Description](#description)\n- [Installation](#installation)\n- [Usage](#usage)\n - [Standard](#standard)\n - [Defaults](#defaults)\n - [Mixed Cases](#mixed-cases)\n - [Aliases](#aliases)\n \n- [Documentation](#documentation)\n- [Testing](#testing)\n- [Scripts](#scripts)\n- [Roadmap](#roadmap)\n- [License](#license)\n\n### Size\n\nApproximate download size of repository, code files within repository, compressed main file, and (just for fun) lines written by the developer including comments etc. Please note that due to file compression, and post download installs/builds such as node module dependencies, the following badges may not exactly reflect download size or space on disk.\n\n![](https://img.shields.io/github/repo-size/blameitonyourisp/funky?style=for-the-badge&labelColor=181b1a&color=779966) ![](https://img.shields.io/github/languages/code-size/blameitonyourisp/funky?style=for-the-badge&labelColor=181b1a&color=779966) ![](https://img.shields.io/bundlephobia/minzip/@13ms/funky?style=for-the-badge&labelColor=181b1a&color=779966) ![](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/blameitonyourisp/funky/master/dist/tokei.json) \n\n\n## Description\n\nFunky is a dead simple jsdoc plugin which introduces the `@funky` tag (and explicit aliases) which is designed to set the kind, access, and scope properties of jsdoc doclets.\n\n```javascript\n/**\n * Vanilla jsdoc tags required to explicitly declare an access specific, scoped\n * function.\n *\n * @function\n * @public\n * @global\n */\n\n/** \n * One simple tag to replace them all, and in the darkness bind them, cutting \n * down on repetitive lines of documentation to achieve the same explicit \n * result.\n *\n * @funky {public|global}\n */\n```\n\n## Installation\n\nIf you are not already using jsdoc in your project(s) then go ahead and checkout the [github repository for jsdoc](https://github.com/jsdoc/jsdoc), otherwise continue with installing this plugin in a package that already has jsdoc installed and configured. This plugin is available from [npm](https://www.npmjs.com), to view there please see the [package page](https://www.npmjs.com/package/@13ms/funky).\n\n```bash\n# install the funky plugin (recommended as a dev dependency)\nnpm install --save-dev @13ms/funky\n```\n\nAs with any plugin, you must also point jsdoc to the funky repository in the node_modules folder. This must be done using a jsdoc config file (as of creating this plugin, there is no way to use plugins through the jsdoc cli). If you are not currently using a config file with jsdoc, please refer to [this page](https://jsdoc.app/about-configuring-jsdoc.html) for information on writing a config file, otherwise ensure that your jsdoc config file includes funky as a plugin (please note that the following is only a fragment of a config file).\n\n```json\n{\n \"plugins\": [ \n \"node_modules/@13ms/funky/\"\n ]\n}\n```\n\n## Usage\n\nFunky syntax is as simple as `@funky {|}` nothing more, nothing less.\n\n### Standard\n\n`@funky` tags follow a simple syntax where the required access and scope values are passed as types in the type field of the `@funky` tag. `@funky` tags ignore any name or description values passed according to jsdoc syntax rules, however a `@funky` tag *must* be passed a type field. If no type field is provided, jsdoc will throw an error when generating documentation. The syntax for a `@funky` tag is `@funky {|}` where the `` and `` are passed in the tag type field, and are the `access` and `scope` values which should be applied to the doclet.\n\nThe available `access` types are as follows `[\"public\", \"package\", \"protected\", \"private\"]`, please [see here](https://jsdoc.app/tags-access.html) for more information about the jsdoc `@access` tag and the following links for information about explicit `access` tags:\n\n- [public](https://jsdoc.app/tags-public.html) for `@public` tag\n- [package](https://jsdoc.app/tags-package.html) for `@package` tag\n- [protected](https://jsdoc.app/tags-protected.html) for `@protected` tag\n- [private](https://jsdoc.app/tags-private.html) for `@private` tag\n\nThe available `scope` types are as follows `[\"global\", \"instance\", \"static\", \"inner\"]`, please see the following links for information about explicit `scope` tags (as of writing this plugin no general `@scope` tag is available in vanilla jsdoc):\n\n- [global](https://jsdoc.app/tags-global.html) for `@global` tag\n- [instance](https://jsdoc.app/tags-instance.html) for `@instance` tag\n- [static](https://jsdoc.app/tags-static.html) for `@static` tag\n- [inner ](https://jsdoc.app/tags-inner.html)for `@inner` tag\n\n```javascript\n/** \n * Funky tags take only type value(s); access first then scope. Any name and or\n * description values provided in jsdoc syntax will be ignored. A funky tag\n * alone with no type field will cause jsdoc to throw an error. All the following\n * tags would produce the same doclet output.\n *\n * @funky {|}\n * @funky {|} \n * @funky {|} - \n */\n```\n\n### Defaults\n\nThe default access for `@funky` tags is `public` since this is the most permissive access type available. The default scope for `@funky` tags is `instance`. The `instance` scope is *not* the highest level scope (`global` scope is a valid jsdoc scope), however `instance` is used as the default scope in order to preserve the module or namespace context of a function contained within a `@module` tagged file, or a function with a `@memberof` tag. This allows a shorter tag to be used such as `@funky {public}` to define a `public` access method within a module file or namespace.\n\nFortunately the default `instance` scope does interfere with methods defined within the `global` which are intended to be documented as such; a tag such as `@funky {public}` used in `global` scope will simply make the method an `instance` of `global` scope.\n\n```javascript\n/** \n * Default access and scope values which are assumed if one or both are missing\n * or if the provided values are not permitted. All the following tags would\n * evaluate to the same jsdoc doclet output thanks to the default values.\n *\n * @funky {public|instance}\n * @funky {invalidAccess|instance}\n * @funky {public|invalidScope}\n * @funky {public}\n * @funky {}\n */\n```\n\n### Mixed Cases\n\nFunky uses case insensitive regex expressions as is used by the vanilla jsdoc `@access` tag in order to validate `access` and `scope` values (see [jsdoc source](https://github.com/jsdoc/jsdoc/blob/main/packages/jsdoc-tag/lib/definitions/core.js#L40) for `@access` tag). This means that any mix of cases can be used in a `@funky` tag.\n\n```javascript\n/** \n * Default access and scope values which are assumed if one or both are missing\n * You may use any combination in funky tags, so the following tags would all\n * evaluate to the same jsdoc doclet output.\n *\n * @funky {private|inner}\n * @funky {PRIVATE|inner}\n * @funky {private|INNER}\n * @funky {pRiVate|InNeR}\n */\n```\n\n### Aliases\n\nFunky uses `@funky` as the main tag for jsdoc, chosen both since it is short and relatively adjacent to the existing `@function` tag. However obviously `@funky` is not an explicit or meaningful tag name. For this reason `@scopedfunction` and `@scopedfunc` are provided as aliases to `@funky`. All lowercase is used for all aliases in order to stay in keeping with other existing vanilla jsdoc tags such as `@typedef` and `@memberof`.\n\n```javascript\n/** \n * All of these are equivalent tags with identical jsdoc doclet outputs.\n *\n * @funky {public|global}\n * @scopedfunction {public|global}\n * @scopedfunc {public|global}\n */\n```\n\n## Documentation\n\nFunky is about as simple as a repository can be; there are no explicit author-generated documentation files other than this README file. For auto-generated jsdoc documentation, please clone the repository and use the appropriate npm script(s) and view the docs in the browser on [localhost](http://localhost:8080).\n\n```bash\n# auto-generate jsdoc documentation\ngit clone https://github.com/blameitonyourisp/funky.git\ncd funky\nnpm install\nnpm serve-docs # will also automatically run script to generate docs and serve docs on http://localhost:8080\n```\n\n## Testing\n\nFunky uses Jest for testing, and a sample directory containing jsdoc comments and empty functions as methods for testing generated output in the browser, please clone the repository and use the appropriate npm script(s) to run the available tests or view sample output in the browser on [localhost](http://localhost:8080).\n\n```bash\n# run tests\ngit clone https://github.com/blameitonyourisp/funky.git\ncd funky\nnpm install\nnpm test # run available tests\nnpm serve-docs-sample # serves sample generated docs on http://localhost:8080\n```\n\n## Scripts\n\nPlease see below for a table of scripts declared in the package.json file. All scripts are listed in alphabetical order, not listed in order of any significance or importance. As with any npm script, they may be run from anywhere in the repository using the command `npm run `. Any relevant bash scripts, node scripts etc. which are used independently by one of the following npm scripts may be found in the scripts directory in the root of the repository.\n\n| Name | Usage |\n| :------------------------ | :----------------------------------------------------------- |\n| `build` | Runs Jest test suite, counts lines of code, and builds package (should the test suite fail, the script will not continue to build the package). |\n| `build-dev` | Builds package, and puts bundled, minified result in dist directory. |\n| `docs` | Builds auto-generated docs using jsdoc, and puts generated files in jsdoc directory. |\n| `docs-sample` | Builds auto-generated docs for the sample code using jsdoc, and puts generated files in jsdoc-sample directory. |\n| `serve-docs` | Builds and serves auto-generated on [localhost](http://localhost:8080). |\n| `serve-docs-sample` | Builds and serves auto-generated for the sample code on [localhost](http://localhost:8080). |\n| `test` | Runs Jest test suite. |\n| `tokei` [^1] | Counts approximate lines of code written by the author, and generates a json endpoint for a line count [shields](https://shields.io/) badge. Please note that this script relies on `tokei`, a CLI application written in Rust. If `tokei` is not installed on the system, then this script will not run. |\n| `watch-docs` | Serves docs on [localhost](http://localhost:8080) and watches src directory using [nodemon](https://www.npmjs.com/package/nodemon), and reloads server upon changes. |\n| `watch-docs-sample` | Serves sample docs on [localhost](http://localhost:8080) and watches src directory using [nodemon](https://www.npmjs.com/package/nodemon), and reloads server upon changes. |\n\n[^1]: At the time of writing, the tokei endpoint for dynamic badges/shields is intermittent and unreliable, showing a 502 bad gateway error. This error also prevents the [shields](https://shields.io/category/size) lines of code badge from rendering correctly, causing all repos to show as having 0 lines of code. The format for the tokei badge URL may be found [here](https://github.com/XAMPPRocky/tokei#badges). To circumvent this, lines of code are being counted \"manually\" using the tokei [rust CLI](https://github.com/XAMPPRocky/tokei) and a json endpoint to generate the badge. As such the lines of code badge may be out of sync with the latest commit, although given that this is a \"just for fun\" metric, it is not of importance.\n\n## Roadmap\n\nFunky is a very simple, feature complete, jsdoc plugin. There are no plans to add to or change this repository in the long term. If you find a bug or think there is a specific feature that should be added or changed, please file a bug report or feature request using this repository's issue tracker.\n\n## License\n\n------\n\n**DISCLAIMER** The author(s) of this repository are in no way legally qualified, and are not providing the end user(s) of this repository with *any* form of legal advice or directions.\n\n------\n\nCopyright (c) 2022 James Reid. All rights reserved.\n\nThis software is licensed under the terms of the MIT license, a copy which may be found in the LICENSE.md file in the root of this repository, or please refer to the text below. For a template copy of the license see one of the following 3rd party sites:\n\n- [opensource](https://opensource.org/license/mit/)\n- [choosealicense](https://choosealicense.com/licenses/mit/)\n- [spdx](https://spdx.org/licenses/MIT)\n\n#### License Text\n\nCopyright 2022 James Reid\n\nPermission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.\n\n","readmeFilename":"README.md"}