simplified jsdoc 3

Related tags

Documentation jsdox
Overview

jsdox npm npm build status

jsdox is a simple jsdoc 3 generator. It pulls documentation tags based on a subset of jsdoc 3 from your javascript files and generates markdown files.

Relies on the JSDoc3 parser to get the full AST including comments.

CLI Options

Usage: jsdox [options] <file | directory>

--config <file> (alias -c): Configuration JSON file.

--All (alias -A): Generates documentation for all available elements including internal methods.

--debug (alias -d): Prints debugging information to the console.

--help (alias -H): Prints help and quits.

--version (alias -v): Prints the current version and quits.

--output <dir> (alias -o): Output directory. Default value is output.

--templateDir <dir> (alias -t): Template directory to use instead of built-in ones.

--index <name> (alias -i): Generates an index with the documentation. An optional file name can be provided as an argument. Default value is index.

--index-sort <type>: Defines how to sort the index. Options are: standard (sorted by name), namespace (sorted by package/module and name), and none (not sorted). Default value is standard.

--recursive (alias -r): Generates documentation in all subdirectories of the source folder.

--respect-recursive (alias --rr): Generate subdirectories and copy the original organization of the sources.

Resources

Related projects

  • grunt-jsdox A grunt task to run jsdox on your project

Author and contributors

  • Pascal Belloncle (psq, Original author)
  • Sam Blowes (blowsie)
  • Todd Henderson (thenderson21)
  • Nic Jansma (nicjansma)
  • Joel Kemp (mrjoelkemp)
  • Ron Korving (ronkorving)
  • Mike MacMillan (mmacmillan)
  • Michael Martin-Smucker (mlms13)
  • Akeem McLennon (bluelaguna)
  • Gabor Sar (gaborsar)
  • Marc Trudel (stelcheck)
  • Anselm Stordeur (anselmstordeur)
  • Vladimir de Turckheim (vdeturckheim)

License

jsdox.js is freely distributable under the terms of the MIT license.

Copyright (c) 2012-2016 Sutoiku

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.

Comments
  • add support for @requires and @member

    add support for @requires and @member

    1. Uses outer jsdoc module rather than embeded one.
    2. Enhances output(currently one file each), adds requires and members fields.

    Reference: jsdoc documents

    USAGE

        /**
           module_description
           @module module_name
           @requires req_1
           @requires req_2
        */
        /** @member */
        var MODULE_MEMBER_1 = [1,2,3];
        /** @member */
        var MODULE_MEMBER_2 = 'abc';
    
        ...
    

    Will be parsed as:

       module_name
       ===
    
       module_description
    
       **Requires:**
    
       + module:req_1
       + module:req_2
    
       **Members:**
    
       + MODULE_MEMBER_1
       + MODULE_MEMBER_2
    
       ...
    
    opened by lemori 20
  • Migrated to jsdoc parser with necessary refactoring of internal methods.

    Migrated to jsdoc parser with necessary refactoring of internal methods.

    TODO

    • [x] Use JSDoc's parser to generate the AST for a file
    • [x] Have analyze extract information based on the new AST structure
    • [x] Refactor generateMD as necessary
    • [x] Remove all old docblock parsing code
    • [x] Refactor tests to not use parsers directly
    • [x] Add a test to ensure that multi-line tag descriptions work with the new parser

    Issues

    • [x] First function's name isn't being rendered in the output
    • [x] Module description shouldn't be a heading

    Fixes #25 Replaces #3

    enhancement 
    opened by mrjoelkemp 18
  • template changes

    template changes

    • normalizing headers to pound format
    • use alternate horizontal rules so you don't get them confused with headers
    • adding types to members
    • types display monospace
    • classes prefixed with "Class:"
    • @example tag support for @module and @function
    • separate @author from @license
    opened by boneskull 10
  • Templatize markdown markup

    Templatize markdown markup

    We currently have the markup for the markdown docs hardcoded (e.g., how many ### go into an heading).

    It would be great for customization if the user could supply a template directory via the cli. The templates could be mustache templates. The template files might have to abide by a particular naming convention like:

    • h1.mustache
    • h2.mustache
    • list-item.mustache
    • toc.mustache (table of contents)
    • ...

    Example template:

    h1.mustache

    # {{value}} 
    

    Thoughts?


    Partially satisfied by #31, but needs to be user-configurable.

    enhancement 
    opened by mrjoelkemp 10
  • Many fixes

    Many fixes

    Hi,

    Fixed:

    • run-test.sh: was just not running
    • test scripts: one was having a wrong count for parse result
    • lint: code lints as per the configuration present
    • bugfix: if i have @param name {String} without a description, the parser would break. now it returns an empty string
    opened by stelcheck 9
  • Documentation Index and subdirectories parsing

    Documentation Index and subdirectories parsing

    • Generates an index (with the -i option) for the documentation of functions and classes with links to detailed documentation and source file.
    • The index is sorted alphabetically.
    • -r option makes jsdox parse the subfolders of the directory given as argument and generates all documentation in the output folder.
    • --rr option makes jsdox parse the subfolders of the directory given as argument and generates all documentation in subfolders with the parsed subfolders name. Those are created in the output folder.
    opened by vdeturckheim 8
  • Replace -rr with just -r?

    Replace -rr with just -r?

    @vdeturckheim What's the difference between --recursive and --respect-recursive? If I did jsdox -r inputDir -o outputDir I'd expect the output directory to have the same structure as the input directory.

    question 
    opened by mrjoelkemp 7
  • fixes, tweaks, functionality

    fixes, tweaks, functionality

    • Fixes
      • fixed incorrect default behavior which was to use all symbols. now defaults to ignoring internal/private functions as before. respects @private tag.
      • fixed problem wherein function-level @description would be duplicated in a @returns tag having no description of its own
      • fixed invalid .jshintrc and removed unused jshint-config.json
      • fixed bad formatting (extra comma) when displaying a member or parameter w/o a @description
    • Enhancements
      • support for @example tag
      • support for @property tag
      • type support for both @property tag and members
    • Display tweaks
      • separated @author tag display from @license tag display in template
      • types now display in monospace
      • class displays as title "Class: " to differentiate from module

    Example output

    opened by boneskull 7
  • Process descriptions for @link tags.

    Process descriptions for @link tags.

    Symbols within the same AST are linked via generated hash targets. Absolute URLs starting with http:// and https:// are linked normally. Any other values are not linked and output as text.

    Note: Cross-AST (aka multi-file) symbol linking could be achieved in the future by creating a global symbol map before generating the output.

    opened by nicksay 5
  • fix undefined

    fix undefined "argv" when using in programatic context

    Programmatic usage of jsdox is pretty broken; try to run it via Gulp as in the documentation example.

    Anyway, this will put a band-aid on the problem, so grunt-jsdox will at least function.

    generateForDir() is too tightly coupled to the CLI and should be refactored.

    opened by boneskull 5
  • Fixes support for glob format (an array of files as input)

    Fixes support for glob format (an array of files as input)

    Jsdox was only processing the first file regardless of how many files were given as input.

    This allows for the syntax:

    jsdox **.js --output docs to parse all js files across all subdirectories and store those .md files in the docs folder

    All tests passed.

    opened by mrjoelkemp 5
  • Bump mustache from 0.8.2 to 3.1.0

    Bump mustache from 0.8.2 to 3.1.0

    Bumps mustache from 0.8.2 to 3.1.0.

    Release notes

    Sourced from mustache's releases.

    v3.1.0

    Added

    • #717: Added support .js files as views in command line tool, by [@​JEStaubach].

    Fixed

    • #716: Bugfix for indentation of inline partials, by [@​yotammadem].

    #716: janl/mustache.js#716 #717: janl/mustache.js#717 [@​JEStaubach]: https://github.com/JEStaubach [@​yotammadem]: https://github.com/yotammadem

    v3.0.2

    Fixed

    Dev

    v3.0.1

    #679: Fix partials not rendering tokens when using custom tags, by @​stackchain.

    v3.0.0

    [3.0.0] / 16 September 2018

    We are very happy to announce a new major version of mustache.js. We want to be very careful not to break projects out in the wild, and adhering to Semantic Versioning we have therefore cut this new major version.

    The changes introduced will likely not require any actions for most using projects. The things to look out for that might cause unexpected rendering results are described in the migration guide below.

    A big shout out and thanks to [@​raymond-lam] for this release! Without his contributions with code and issue triaging, this release would never have happened.

    Major

    • #618: Allow rendering properties of primitive types that are not objects, by [@​raymond-lam].
    • #643: Writer.prototype.parse to cache by tags in addition to template string, by [@​raymond-lam].
    • #664: Fix Writer.prototype.parse cache, by [@​seminaoki].

    Minor

    • #673: Add tags parameter to Mustache.render(), by [@​raymond-lam].
    ... (truncated)
    Changelog

    Sourced from mustache's changelog.

    [3.1.0] / 13 September 2019

    Added

    • #717: Added support .js files as views in command line tool, by [@​JEStaubach].

    Fixed

    • #716: Bugfix for indentation of inline partials, by [@​yotammadem].

    [3.0.3] / 27 August 2019

    Added

    • #713: Add test cases for custom functions in partials, by [@​wol-soft].

    Fixed

    • #714: Bugfix for wrong function output in partials with indentation, by [@​phillipj].

    [3.0.2] / 21 August 2019

    Fixed

    • #705: Fix indentation of partials, by [@​kevindew] and [@​yotammadem].

    Dev

    • #701: Fix test failure for Node 10 and above, by [@​andersk].
    • #704: Lint all test files just like the source files, by [@​phillipj].
    • Start experimenting & comparing GitHub Actions vs Travis CI, by [@​phillipj].

    [3.0.1] / 11 November 2018

    [3.0.0] / 16 September 2018

    We are very happy to announce a new major version of mustache.js. We want to be very careful not to break projects out in the wild, and adhering to Semantic Versioning we have therefore cut this new major version.

    The changes introduced will likely not require any actions for most using projects. The things to look out for that might cause unexpected rendering results are described in the migration guide below.

    A big shout out and thanks to [@​raymond-lam] for this release! Without his contributions with code and issue triaging, this release would never have happened.

    Major

    • #618: Allow rendering properties of primitive types that are not objects, by [@​raymond-lam].
    ... (truncated)
    Commits
    • b28bf2c :ship: bump to version 3.1.0
    • 81b0fab Run GitHub Actions tests on PRs as well
    • d820d25 Fix indentation of inline partials (#716)
    • 13cde04 Support .js views with functions in CLI (#717)
    • 96cb5ef :ship: bump to version 3.0.3
    • 4c9ef8f Bugfix for wrong functions output in partials with indentation (#714)
    • c4e56ef Add test cases for custom functions in partials (#713)
    • 6c3608b :ship: bump to version 3.0.2
    • 619c928 Delete old GitHub Actions workflow file
    • fc8eb5d Convert to new GitHub Actions yaml format
    • Additional commits viewable in compare view
    Maintainer changes

    This version was pushed to npm by flipp, a new releaser for mustache since your current version.


    Dependabot compatibility score

    Dependabot will resolve any conflicts with this PR as long as you don't alter it yourself. You can also trigger a rebase manually by commenting @dependabot rebase.


    Dependabot commands and options

    You can trigger Dependabot actions by commenting on this PR:

    • @dependabot rebase will rebase this PR
    • @dependabot recreate will recreate this PR, overwriting any edits that have been made to it
    • @dependabot merge will merge this PR after your CI passes on it
    • @dependabot squash and merge will squash and merge this PR after your CI passes on it
    • @dependabot cancel merge will cancel a previously requested merge and block automerging
    • @dependabot reopen will reopen this PR if it is closed
    • @dependabot ignore this [patch|minor|major] version will close this PR and stop Dependabot creating any more for this minor/major version (unless you reopen the PR or upgrade to it yourself)
    • @dependabot ignore this dependency will close this PR and stop Dependabot creating any more for this dependency (unless you reopen the PR or upgrade to it yourself)
    • @dependabot use these labels will set the current labels as the default for future PRs for this repo and language
    • @dependabot use these reviewers will set the current reviewers as the default for future PRs for this repo and language
    • @dependabot use these assignees will set the current assignees as the default for future PRs for this repo and language
    • @dependabot use this milestone will set the current milestone as the default for future PRs for this repo and language

    You can disable automated security fix PRs for this repo from the Security Alerts page.

    dependencies 
    opened by dependabot[bot] 0
  • NPM Mustache vulnerability

    NPM Mustache vulnerability

    You should update the version.

    def14nt@lizard:~/Desktop/~~REDACTED~~> !!
    npm audit
    
                           === npm audit security report ===
    
    ┌──────────────────────────────────────────────────────────────────────────────┐
    │                                Manual Review                                 │
    │            Some vulnerabilities require your attention to resolve            │
    │                                                                              │
    │         Visit https://go.npm.me/audit-guide for additional guidance          │
    └──────────────────────────────────────────────────────────────────────────────┘
    ┌───────────────┬──────────────────────────────────────────────────────────────┐
    │ High          │ Cross-Site Scripting                                         │
    ├───────────────┼──────────────────────────────────────────────────────────────┤
    │ Package       │ mustache                                                     │
    ├───────────────┼──────────────────────────────────────────────────────────────┤
    │ Patched in    │ >=2.2.1                                                      │
    ├───────────────┼──────────────────────────────────────────────────────────────┤
    │ Dependency of │ jsdox [dev]                                                  │
    ├───────────────┼──────────────────────────────────────────────────────────────┤
    │ Path          │ jsdox > mustache                                             │
    ├───────────────┼──────────────────────────────────────────────────────────────┤
    │ More info     │ https://nodesecurity.io/advisories/62                        │
    └───────────────┴──────────────────────────────────────────────────────────────┘
    found 1 high severity vulnerability in 2095 scanned packages
    
    opened by ghost 0
  • Recursive command doesn't ignore non-JS files

    Recursive command doesn't ignore non-JS files

    When I run the jsdox command recursively on a directory, debug shows that it's processing .txt, .json, and other file types. When those file types are hit, jsdox bails out with an exception, which means I can't recursively generate documentation.

    It should allow a file mask (I've not seen an example supporting this). The jsdox website claimed a recursive directory parse would only pick up .js files, but apparently that's untrue.

    opened by intel352 0
  • Generated paths do not work when generated content is pushed to Git.

    Generated paths do not work when generated content is pushed to Git.

    Love the generator, has a lot of promise, but...

    I'm generating our api with the intent of using it as browsable content on our Git server (in our case GitLab). I have pointed to a templatesDir and that appears to work for customizing the appearance of a class, but for the life of me I cannot effect what is rendered in the contentsFile. For the contentsFile, the generated paths are all wrong. Because I build this on a windows machine, it uses backslashes in the paths, which means it all fails when I upload it to GitLab. Users can see the contentsFile but all links within it, use backslashes not forward slashes so none of the links are valid. I used string-replace to get round this but the paths start with a slash (/) and in order to get it to work correctly so all paths are relative to the contentFile, I need it to start with dot-slash (./).

    Essentially, there needs to be a means of formatting the path so developers not fortunate enough to be allowed use anything other than windows in their company, have a chance at using this.

    opened by steeren 0
Owner
Sutoiku, Inc.
Sutoiku, Inc.
JavaScript documentation generator for node using markdown and jsdoc

Dox Dox is a JavaScript documentation generator written with node. Dox no longer generates an opinionated structure or style for your docs, it simply

TJ Holowaychuk 2.1k Jan 7, 2023
JSDoc generator for JavaScript, TypeScript using AI. (VSCode extension)

JSDoc generator for JavaScript, TypeScript using AI. (VSCode extension)

Amir Reza Dalir 3 Aug 18, 2022
Simplified JavaScript Jargon

Simplified JavaScript Jargon (short SJSJ) is a community-driven attempt at explaining the loads of buzzwords making the current JavaScript ecosystem i

Kitty Giraudel 2.3k Dec 30, 2022
🏊🏾 Simplified HTTP request client.

Deprecated! As of Feb 11th 2020, request is fully deprecated. No new changes are expected to land. In fact, none have landed for some time. For more i

request 25.6k Jan 4, 2023
An unofficial, simplified version of the @Shopify/koa-shopify-auth middleware library.

simple-koa-shopify-auth https://www.npmjs.com/package/simple-koa-shopify-auth NOTE: This package is not maintained by or affiliated with Shopify. Desc

David 20 Nov 7, 2022
A simplified Telegraf plugin to provide users with a great interface.

telegraf-pagination A simplified Telegraf plugin to provide users with a great interface. Getting started Prerequisites You need to have telegraf inst

Alisher Ortiqov 8 Nov 21, 2022
AWS Lambda and API Gateway, simplified for Javascript

alanajs AWS Lambda and API Gateway, simplified for JavaScript About alanajs Make setting up Lambda microservices easier than ever. alanajs is a free,

OSLabs Beta 64 Aug 1, 2022
Data-driven development, simplified.

CONTRACTUAL Table of Contents 0. Brief 1. Features 2. Installation 2.1 Download Installer 2.2 Fork and Clone Repo 3. How to Use 3.1 Contract Builder 3

OSLabs Beta 50 Nov 8, 2022
A simplified list crud that adds, removes and edits items

To-do list This project is as simplified todo list crud. Built With HTML CSS JavaScript Webpack Live version See live version Getting Started To get a

Fernando Saldaña 7 Apr 2, 2022
⚡ It is a simplified database module with multiple functions that you can use simultaneously with sqlite, yaml, firebase and json.

Prisma Database Developed with ?? by Roxza ⚡ An easy, open source database ?? Installation npm i prisma.db --save yarn add prisma.db ?? Importing impo

Roxza 21 Jan 3, 2023
Motionia is a lightweight simplified on demand animation library

The Ultimate & smart JS animation library! Simple fast , flexible & easy to integrate. No need to write page long CSS Keyframes that consumes a lot of

Abhi 324 Dec 30, 2022
🐬 A simplified implementation of TypeScript's type system written in TypeScript's type system

?? HypeScript Introduction This is a simplified implementation of TypeScript's type system that's written in TypeScript's type annotations. This means

Ronen Amiel 1.8k Dec 20, 2022
A simplified jQuery date and time picker

jSunPicker A simplified jQuery date and time picker Why another Date picker? There are numerous date, time pickers out there. However, each of those l

null 1 May 31, 2022
An overly simplified Angular tool for interacting with Smart Contracts, demod at ng-conf 2022.

AngularOperator This is a sample repo and tool created for ng-conf 2022. It contains a normal Angular app designed to interact with the blockchain. It

Stephen Fluin 8 Oct 7, 2022
REST API simplified.

Deepkit REST REST API simplified npm i \ @deepkit-rest/http-extension \ @deepkit-rest/rest-core \ @deepkit-rest/rest-crud Overview DeepKit REST

DeepKit REST 8 Dec 30, 2022