Funky
A jsdoc plugin for quickly creating scoped and access tagged functions. This repository is hosted on github, if you're already reading this there, then great! Otherwise browse the repository here.
Table of Contents
Size
Approximate 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.
Description
Funky 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.
/**
* Vanilla jsdoc tags required to explicitly declare an access specific, scoped
* function.
*
* @function
* @public
* @global
*/
/**
* One simple tag to replace them all, and in the darkness bind them, cutting
* down on repetitive lines of documentation to achieve the same explicit
* result.
*
* @funky {public|global}
*/Installation
If you are not already using jsdoc in your project(s) then go ahead and checkout the github repository for jsdoc, otherwise continue with installing this plugin in a package that already has jsdoc installed and configured. This plugin is available from npm, to view there please see the package page.
# install the funky plugin (recommended as a dev dependency)
npm install --save-dev @13ms/funkyAs 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 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).
{
"plugins": [
"node_modules/@13ms/funky/"
]
}Usage
Funky syntax is as simple as @funky {<access>|<scope>} nothing more, nothing less.
Standard
@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 {<access>|<scope>} where the <access> and <scope> are passed in the tag type field, and are the access and scope values which should be applied to the doclet.
The available access types are as follows ["public", "package", "protected", "private"], please see here for more information about the jsdoc @access tag and the following links for information about explicit access tags:
-
public for
@publictag -
package for
@packagetag -
protected for
@protectedtag -
private for
@privatetag
The 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):
/**
* Funky tags take only type value(s); access first then scope. Any name and or
* description values provided in jsdoc syntax will be ignored. A funky tag
* alone with no type field will cause jsdoc to throw an error. All the following
* tags would produce the same doclet output.
*
* @funky {<access>|<scope>}
* @funky {<access>|<scope>} <name>
* @funky {<access>|<scope>} <name> - <description>
*/Defaults
The 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.
Fortunately 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.
/**
* Default access and scope values which are assumed if one or both are missing
* or if the provided values are not permitted. All the following tags would
* evaluate to the same jsdoc doclet output thanks to the default values.
*
* @funky {public|instance}
* @funky {invalidAccess|instance}
* @funky {public|invalidScope}
* @funky {public}
* @funky {}
*/Mixed Cases
Funky 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 for @access tag). This means that any mix of cases can be used in a @funky tag.
/**
* Default access and scope values which are assumed if one or both are missing
* You may use any combination in funky tags, so the following tags would all
* evaluate to the same jsdoc doclet output.
*
* @funky {private|inner}
* @funky {PRIVATE|inner}
* @funky {private|INNER}
* @funky {pRiVate|InNeR}
*/Aliases
Funky 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.
/**
* All of these are equivalent tags with identical jsdoc doclet outputs.
*
* @funky {public|global}
* @scopedfunction {public|global}
* @scopedfunc {public|global}
*/Documentation
Funky 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.
# auto-generate jsdoc documentation
git clone https://github.com/blameitonyourisp/funky.git
cd funky
npm install
npm serve-docs # will also automatically run script to generate docs and serve docs on http://localhost:8080Testing
Funky 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.
# run tests
git clone https://github.com/blameitonyourisp/funky.git
cd funky
npm install
npm test # run available tests
npm serve-docs-sample # serves sample generated docs on http://localhost:8080Scripts
Please 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 <script-name>. 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.
| Name | Usage |
|---|---|
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). |
build-dev |
Builds package, and puts bundled, minified result in dist directory. |
docs |
Builds auto-generated docs using jsdoc, and puts generated files in jsdoc directory. |
docs-sample |
Builds auto-generated docs for the sample code using jsdoc, and puts generated files in jsdoc-sample directory. |
serve-docs |
Builds and serves auto-generated on localhost. |
serve-docs-sample |
Builds and serves auto-generated for the sample code on localhost. |
test |
Runs Jest test suite. |
tokei 1
|
Counts approximate lines of code written by the author, and generates a json endpoint for a line count shields 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. |
watch-docs |
Serves docs on localhost and watches src directory using nodemon, and reloads server upon changes. |
watch-docs-sample |
Serves sample docs on localhost and watches src directory using nodemon, and reloads server upon changes. |
Roadmap
Funky 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.
License
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.
Copyright (c) 2022 James Reid. All rights reserved.
This 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:
License Text
Copyright 2022 James Reid
Permission 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:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE 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.
-
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 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. To circumvent this, lines of code are being counted "manually" using the tokei rust CLI 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. ↩