esdoc / esdoc-plugins Goto Github PK

View Code? Open in Web Editor NEW

140.0 140.0 77.0 786 KB

License: MIT License

JavaScript 92.63% CSS 4.22% HTML 2.83% Shell 0.17% TypeScript 0.15%

esdoc-plugins's Introduction

ESDoc

ESDoc is a documentation generator for JavaScript.
Please try it out!

Features

Generates good documentation.
Measures documentation coverage.
Integrate test codes into documentation.
Integrate manual into documentation.
Parse ECMAScript proposals.
ESDoc Hosting Service

Users

ESDoc (self-hosting 😄)
RxJS
Sketch API

And more.

Quick Start

# Move to a your project directory.
cd your-project/

# Install ESDoc and standard plugin.
npm install --save-dev esdoc esdoc-standard-plugin

# Create a configuration file.
echo '{
  "source": "./src",
  "destination": "./docs",
  "plugins": [{"name": "esdoc-standard-plugin"}]
}' > .esdoc.json

# Run ESDoc.
./node_modules/.bin/esdoc

# View a documentation
open ./docs/index.html

Document

please visit esdoc.org to see more documentation.

License

MIT

Author

Ryo Maruyama@h13i32maru

esdoc-plugins's People

Contributors

Stargazers

Watchers

Forkers

nmchau gerard2perez pzuraq jaxx2104 zigen andersevenrud destenson pat841 sumolari moshest bkcore aebabis julienkode samskivert luk707 shfx asis robertmain tchakabam bencevans nc-kreiserm davidedaniel justinbeckwith drorgl mixer paztis josephschmitt jan-molak derwhity verikon kagawagao onlicar diokuz andsouto xal3ph xingkongbj alexssandroreis axtell citguy mikewesthad protolambda alexdiliberto douglaslmiller shuuji3 scriptcoded fkm arikimolloy phueper design1online imcuttle paperscz mbelsky erisu libook acidburn0zzz retzger ingewortel juliokleeen setheum-js k88manish esdoc-latest fab1o trpeel gaybro8777 boomerchi qpc-github tkoelpin iq-scm oterral

esdoc-plugins's Issues

React component documentation not generated

First off this is an awesome lib!

One thing though, I'm not getting any docs generated for react components, even with the esdoc-react-plugin installed. It just seems to skip them.

I'm using create-react-app, a general component would look something like

import React, { Component } from 'react';

/**
 * @class MyComponent - hello world component
 *
 */
export default class MyComponent extends Component {
  constructor(props) {
    super(props);

    this.state = { active: false };
  }

  render() {
    return (this.state.active) ? null : <div> hello world </div>;
  }
}

Any ideas?

esdoc-importpath-plugin puts trailing slash on import path

Here is my .esdoc.json:

... 
{
  "name": "esdoc-importpath-plugin",
  "option": {
    "replaces": [
      { "from": ".*", "to": "" }
    ]
  }
}
...

The output docs has imports like this:

import {all} from '@user/package/'

How do I remove the trailing slash?

esdoc-vue-plugin

Hi there,

Does a vue plugin exists ? Is being created ?

If so, do you have links ?

Thanks ?

TypeError: Cannot read property 'kind' of undefined when using 'esdoc-jsx-plugin'

It looks like that using "esdoc-jsx-plugin" broke esdoc with the following message:

TypeError: Cannot read property 'kind' of undefined
  at SearchIndexBuilder._getOutputFileName (/[.....whatever.....]/node_modules/esdoc-publish-html-plugin/out/src/Builder/DocBuilder.js:585:17)
  at SearchIndexBuilder._getOutputFileName (/[.....whatever.....]/node_modules/esdoc-publish-html-plugin/out/src/Builder/DocBuilder.js:598:23)
  at SearchIndexBuilder._getURL (/[.....whatever.....]/node_modules/esdoc-publish-html-plugin/out/src/Builder/DocBuilder.js:570:29)
  at SearchIndexBuilder.exec (/[.....whatever.....]/node_modules/esdoc-publish-html-plugin/out/src/Builder/SearchIndexBuilder.js:52:20)
  at Plugin._exec (/[.....whatever.....]/node_modules/esdoc-publish-html-plugin/out/src/Plugin.js:97:66)
  at Plugin.onPublish (/[.....whatever.....]/node_modules/esdoc-publish-html-plugin/out/src/Plugin.js:71:10)
  at Plugin._execHandler (/[.....whatever.....]/node_modules/esdoc/out/src/Plugin/Plugin.js:55:26)
  at Plugin.onPublish (/[.....whatever.....]/node_modules/esdoc/out/src/Plugin/Plugin.js:154:10)
  at Function._publish (/[.....whatever.....]/node_modules/esdoc/out/src/ESDoc.js:354:24)
  at Function.generate (/[.....whatever.....]/node_modules/esdoc/out/src/ESDoc.js:149:10)

Here is my config:

module.exports = {
source: './src',
destination: './docs',
includes: ['\\.(js|jsx)'],
excludes: ['\\.config\\.js$', 'utils'],
plugins: [
  { name: 'esdoc-standard-plugin' },
  { name: 'esdoc-flow-type-plugin' },
  { name: 'esdoc-jsx-plugin' },
  { name: 'esdoc-react-plugin' },
  { name: 'esdoc-coverage-plugin' },
],
};

if I comment this line from the plugins' array: { name: 'esdoc-jsx-plugin' } it work properly but no .jsx file were included.
Unfortunately, I am documenting a React app 😄

mailto link is broken esdoc-publish-html-plugin ManualDocBuilder.js

In esdoc-publish-html-plugin/src/Builder/ManualDocBuilder.js

$root.find('a').each((i, el) => {
  const $el = (0, _cheerio2.default)(el);
  const href = $el.attr('href');
  if (!href) return;
  if (href.match(/^http[s]?:/)) return;
  if (href.charAt(0) === '/') return;
  if (href.charAt(0) === '#') return;
  $el.attr('href', `./manual/${href}`);
});

This code adds './manual/' to the mailto address inside of:
<a href="mailto:[email protected]">[email protected]</a>

which breaks the link. Please help to fix this. Maybe add a line:

if (href.match(/^mailto:)) return;

Error in inject script (and style)

let i = 0;
for (const style of this._option.styles) {
  const src = `./inject/css/${i}-${path.basename(style)}`;
  $('head').append(`<link rel="stylesheet" href="${src}"/>`);
}

I never increments. Maybe a leftover when loop was written differently?

Cross-site Scripting (XSS) via Data URIs [SEVERITY: HIGH]

https://www.bithound.io/github/sinnerschrader/esdoc-custom-theme/master/dependencies/npm/esdoc-publish-html-plugin#security-advisories

Discovered in a nested dependency:[email protected]@0.3.6

https://snyk.io/vuln/npm:marked:20170112?utm_source=bithound

Cross-site Scripting (XSS) via Data URIs

Affecting marked package, versions <0.3.7

ECMAScript proposals bug: Cannot read property 'charAt' of undefined

Repository to produce bug: https://github.com/maple-leaf/esdoc-proposals-plugin-bug-reproduce

source code in repo:

const x = {};
x['d'] = function() {
    console.log('test');
};

Install npm deps and generate doc by npx esdoc will raise error:

Cannot read property 'charAt' of undefined

react tags not in output

Hi,

I am using esdoc version 1.0.4 for my create-react-app app and I am expericiencing some issues. I guess I am making a beginners fault, but I don't see where.

This is my .esdoc.json:

{
  "source": "./src",
  "destination": "./docs",
  "plugins": [
    {"name": "esdoc-jsx-plugin", "option": {"enable": true}},
    {
      "name": "esdoc-ecmascript-proposal-plugin",
      "option": {
        "enable":true,
        "classProperties": true,
        "objectRestSpread": true,
        "doExpressions": true,
        "functionBind": true,
        "functionSent": true,
        "asyncGenerators": true,
        "decorators": true,
        "exportExtensions": true,
        "dynamicImport": true
      }
    },
      {"name": "esdoc-standard-plugin"},
    {
      "name": "esdoc-react-plugin", 
      "option": {"enable": true}
    }
  ]
}

And I have for instance the following snippet as a Component:

** represents the App component. App has the url to the server as props. 
 *   @reactProps {String} url - The url of the server
 *   @example url="http://192.168.5.231:8099/json"
 */
class App extends Component {

  /**
   * creates an instance of the App component
   */
  constructor(){
    super();
  }

  /** showMessage 
    @param msg {string} - The error message
   */
  showMessage = (msg) => {
  }
}

In the output @reactProps is missing.
And the showMessage is not recognized as a function, but as a member, which causes my params to be left out of the output.

I have tried to change the order of the plugins, but got the same result. Then I tried to leave some of them out, but that led to the expected parsing errors.

Can someone explain what I am doing wrong?

Thanks

Jan

Class decorator with object argument - `SyntaxError: Invalid regular expression`

Using

  "dependencies": {
    "esdoc": "^1.0.3",
    "esdoc-ecmascript-proposal-plugin": "^1.0.0",
    "esdoc-jsx-plugin": "^1.0.0",
    "esdoc-standard-plugin": "^1.0.0"
  }

When using a class decorator with an object as argument, I run into this error:

SyntaxError: Invalid regular expression: /[~]Logger
  level: 'debug'
})$/: Unmatched ')'
    at RegExp (<anonymous>)
    at ClassDocBuilder._findByName (D:\Projects\xai-jbm\jovi-r3r-experiments\docs\esdoc\node_modules\esdoc-publish-html-plugin\out\src\Builder\DocBuilder.js:116:20)
    at ClassDocBuilder._buildDocLinkHTML (D:\Projects\xai-jbm\jovi-r3r-experiments\docs\esdoc\node_modules\esdoc-publish-html-plugin\out\src\Builder\DocBuilder.js:768:22)
    at ClassDocBuilder._buildDecoratorHTML (D:\Projects\xai-jbm\jovi-r3r-experiments\docs\esdoc\node_modules\esdoc-publish-html-plugin\out\src\Builder\DocBuilder.js:1012:25)
    at ClassDocBuilder._buildClassDoc (D:\Projects\xai-jbm\jovi-r3r-experiments\docs\esdoc\node_modules\esdoc-publish-html-plugin\out\src\Builder\ClassDocBuilder.js:87:32)
    at ClassDocBuilder.exec (D:\Projects\xai-jbm\jovi-r3r-experiments\docs\esdoc\node_modules\esdoc-publish-html-plugin\out\src\Builder\ClassDocBuilder.js:31:32)
    at Plugin._exec (D:\Projects\xai-jbm\jovi-r3r-experiments\docs\esdoc\node_modules\esdoc-publish-html-plugin\out\src\Plugin.js:93:63)
    at Plugin.onPublish (D:\Projects\xai-jbm\jovi-r3r-experiments\docs\esdoc\node_modules\esdoc-publish-html-plugin\out\src\Plugin.js:71:10)
    at Plugin._execHandler (D:\Projects\xai-jbm\jovi-r3r-experiments\docs\esdoc\node_modules\esdoc\out\src\Plugin\Plugin.js:55:26)
    at Plugin.onPublish (D:\Projects\xai-jbm\jovi-r3r-experiments\docs\esdoc\node_modules\esdoc\out\src\Plugin\Plugin.js:154:10)

The stack trace is from this source code:

@Logger('Raycasting', { level: 0 })
export default class Raycasting { ... }

In general:

function Decorator() {}

// works:
@Decorator()
export default class MyClass { }

// works:
@Logger('foo')
export default class MyClass { }

// works:
const options = { level: 'debug' };
@Logger('foo', options )
export default class MyClass { }

// does not work:
@Logger({ level: 'debug' })
export default class MyClass { }

// does not work:
@Logger('foo', { level: 'debug' })
export default class MyClass { }

Maintainance status

There hasn't been any activity since Nov 12th 2017.

Please tell me that this is not another abandoned documentation tool.

I am really happy with esdoc and would love to help you if help is accepted.
There seem to be some issues that should be easy to review and fix.

e.g. #50

Thx for all the work so far.

Crash esdoc-accessor-plugin "Cannot read property 'charAt' of null"

.\one\node_modules\esdoc-accessor-plugin\src\Plugin.js:16
        if (autoPrivate && doc.name.charAt(0) === '_') {
                                   ^

TypeError: Cannot read property 'charAt' of null
    at Plugin.onHandleDocs (.\one\node_modules\esdoc-accessor-plugin\src\Plugin.js:16:36)
    at Plugin._execHandler (.\one\node_modules\esdoc\out\src\Plugin\Plugin.js:55:26)
    at Plugin.onHandleDocs (.\one\node_modules\esdoc\out\src\Plugin\Plugin.js:135:10)
    at Function.generate (.s\one\node_modules\esdoc\out\src\ESDoc.js:133:32)
    at ESDocCLI.exec (.\one\node_modules\esdoc\out\src\ESDocCLI.js:71:23)
    at Object.<anonymous> (.\one\node_modules\esdoc\out\src\ESDocCLI.js:182:7)
    at Module._compile (module.js:624:30)
    at Object.Module._extensions..js (module.js:635:10)
    at Module.load (module.js:545:32)
    at tryModuleLoad (module.js:508:12)

ESDoc is a nice library, but the error handling in 1.x (around the regular-expression based parsing) still makes it difficult for the user to determine the error if they have made a mistake on the doc syntax.

For example, one such error lead to the following:

TypeError: Cannot read property 'replace' of undefined
  at inner.split.map.v (/Users/bspies/GW/Source/portals/portals-frontend/frontend/node_modules/esdoc-publish-html-plugin/out/src/Builder/DocBuilder.js:700:30)
  at Array.map (native)
  at ClassDocBuilder._buildTypeDocLinkHTML (/Users/bspies/GW/Source/portals/portals-frontend/frontend/node_modules/esdoc-publish-html-plugin/out/src/Builder/DocBuilder.js:697:43)
  at ClassDocBuilder._buildSignatureHTML (/Users/bspies/GW/Source/portals/portals-frontend/frontend/node_modules/esdoc-publish-html-plugin/out/src/Builder/DocBuilder.js:845:36)

Even a simple try-catch block that pretty-prints the contents of matched would be much better than this.

Thanks, and keep up the good work!

Correctly resolve class constructors integrate test plugin

When documenting my tests - if I refer to the {constructor} identifier in my it() or test() blocks it links that test to every single constructor, rather than just the constructor of identifier listed in describe()

That means that given the following:

/**
 * @test {Line}
 */
describe('Line', () => {

    /**
     * @test {constructor}
     */
    it('can be created from two points and uses them as start and end points', () => {
        const start = new Point(6, 8);
        const end   = new Point(12, 6);

        expect(() => new Line(start, end)).not.toThrow(TypeError);
    });
);

that test would appear on every constructor in my project, rather than just the constructor for Line.

This can be mitigated, by putting the class name and # in front of constructor like so:

/**
 * @test {Line}
 */
describe('Line', () => {

    /**
     * @test {Line#constructor}
     */
    it('can be created from two points and uses them as start and end points', () => {
        const start = new Point(6, 8);
        const end   = new Point(12, 6);

        expect(() => new Line(start, end)).not.toThrow(TypeError);
    });
);

However, it would be nice if the esdoc plugin could just figure this out

Security vulnerability in using [email protected]

Link: https://nodesecurity.io/advisories/531
Please update marked to fix this issue

GitBook integration?

Happy to see esdoc updated recently. Its great for code documentation, but I've found it difficult to manage in respect of putting together a user manual. I've since discovered GitBook and noted that it has an integration point with JsDoc. It seems that the basis of the integration is jsdoc-to-markdown. How would you suggest integrating EsDoc with Gitbook? Is there an EsDoc plugin already available?

[Typescript Plugin] - Spread operator not handled

I have a function in typescript that returns a promise. The spread operator is used to merge properties of two objects. ESDoc fails on that line and runs smoothly when I cut it.

return new Promise((resolve, reject) => {
    this.service.findByUserId(userId, relationsUser)
    .then(async (user: User) => {
        if (!user) throw new NotFoundException('User does not exist');
        const authUser = await this.service.getAuth0UserProfile(user.userId);
        resolve({ ...authUser, ...user}); <-- Does not work
    })
    .catch(reason => reject(reason));
});

Any idea how to solve this? Thanks!

Does logo only support .png format?

It seems that it is not working with .svg file.

Manual assets not generated when no files specified

When you use such configuration:

      "manual": {
        "index": "./manual/index.md",
        "asset": "./manual/asset",
        "files": ["./manual/overview.md"]
      },

Both - assets and files are copied to the output site. That's OK.

When you use such configuration:

      "manual": {
        "index": "./manual/index.md",
        "asset": "./manual/asset"
      },

esdoc will throw an error:

assert.js:85
  throw new assert.AssertionError({
  ^
AssertionError: undefined == true
    at Plugin._setDefault (C:\Users\jni\WebstormProjects\cloudify-stage\node_modules\esdoc-integrate-manual-plugin\src\Plugin.js:23:5)
    at Plugin._exec (C:\Users\jni\WebstormProjects\cloudify-stage\node_modules\esdoc-integrate-manual-plugin\src\Plugin.js:14:10)
    at Plugin.onHandleDocs (C:\Users\jni\WebstormProjects\cloudify-stage\node_modules\esdoc-integrate-manual-plugin\src\Plugin.js:10:10)
    at Plugin._execHandler (C:\Users\jni\WebstormProjects\cloudify-stage\node_modules\esdoc\out\src\Plugin\Plugin.js:55:26)
    at Plugin.onHandleDocs (C:\Users\jni\WebstormProjects\cloudify-stage\node_modules\esdoc\out\src\Plugin\Plugin.js:135:10)
    at Function.generate (C:\Users\jni\WebstormProjects\cloudify-stage\node_modules\esdoc\out\src\ESDoc.js:133:32)
    at ESDocCLI.exec (C:\Users\jni\WebstormProjects\cloudify-stage\node_modules\esdoc\out\src\ESDocCLI.js:71:23)
    at Object.<anonymous> (C:\Users\jni\WebstormProjects\cloudify-stage\node_modules\esdoc\out\src\ESDocCLI.js:182:7)
    at Module._compile (module.js:570:32)
    at Object.Module._extensions..js (module.js:579:10)

I would expect that such configuration will copy assets from the directory I specified to manual/asset. I would like to use static content in index.

When you use such configuration:

      "manual": {
        "index": "./manual/index.md",
        "asset": "./manual/asset",
        "files": [ ]
      },

esdoc will generate output but without assets.

esdoc-integrate-manual-plugin `files` option should accept wildcard or regex matches

It should be possible to use wildcards or regex patterns to match multiple files instead of needing to list every single manual file explicitly.

esdoc-typescript-plugin error: "Cannot read property 'program' of undefined"

config:

{    
	"source": "./ClientApp",    
	"destination": "./docs",    
	"plugins": [        
	{ "name": "esdoc-standard-plugin" },
	{ "name": "esdoc-typescript-plugin", "option": { "enable": true } }
	]
}

error:

...etc\DocFactory.js:135
    for (const exportNode of this._ast.program.body) {
                                      ^

TypeError: Cannot read property 'program' of undefined

It works fine without the typescript plugin, but fails when it is added.

ESDoc not able to generate documentation if render method has a JSX comment

Hello,

I am not able to create documentation for the React render method if it contains a JSX comment.

=== JSX comment example ===
{/* Test Coment */}

Is there any configuration by which I can ignore these comments and generate comments for the render method?

=== Render method example ===
/**
* render is a react lifecycle method.
* @access private
* @return {ReactElement} HTML
*/
render () {
        let _this = this;
        return (
            <div>
                {/* Test Coment */}
             </div>
        )
}

=== ESDOC json config file ===
{
  "source": "..",
  "destination": "docs",
  "includes": ["\\.(js|jsx)$"],
  "plugins": [
    {
      "name": "esdoc-standard-plugin",
      "option": {
        "lint": {"enable": false},
        "coverage": {"enable": true},
        "accessor": {
          "access": ["public", "protected"],
          "autoPrivate" : false
        },
        "undocumentIdentifier" : {"enable": false},
        "typeInference": {"enable": true},
      }
    },
    {
      "name": "esdoc-jsx-plugin", 
      "option": {"enable": true}
    },
    {
      "name": "esdoc-react-plugin", 
      "option": {"enable": true}
    },
    {
      "name": "esdoc-lint-plugin",
      "option": {"enable": true}
    }
  ]
}

esdoc-flow-type-plugin: missing support for importing type(s)

import type { Type } from 'flow-runtime'
import type { Store } from './store'
import { type Errors } from './errors'

esdoc-flow-type-plugin fails to parse those lines because of type keyword. It throws error:

parse: /Users/alek/Desktop/pros/bs/src/types.js
warning: could not parse the following code. if you want to use ECMAScript proposals, see https://esdoc.org/manual/feature.html#ecmascript-proposal
/Users/alek/Desktop/pros/bs/src/types.js
3| import t, { reify } from 'flow-runtime'
4| import type { Type } from 'flow-runtime'
5| import type { Store } from './store'
6| import { type Errors } from './errors'
7| 
8| /**
9|  * * Method name must consist from one or more modules

TypeError: Cannot read property 'start' of undefined
    at Plugin._formatResult (/Users/alek/Desktop/pros/bs/node_modules/esdoc-lint-plugin/src/Plugin.js:141:42)
    at Plugin.onPublish (/Users/alek/Desktop/pros/bs/node_modules/esdoc-lint-plugin/src/Plugin.js:33:26)
    at Plugin._execHandler (/Users/alek/Desktop/pros/bs/node_modules/esdoc/out/src/Plugin/Plugin.js:55:26)
    at Plugin.onPublish (/Users/alek/Desktop/pros/bs/node_modules/esdoc/out/src/Plugin/Plugin.js:154:10)
    at Function._publish (/Users/alek/Desktop/pros/bs/node_modules/esdoc/out/src/ESDoc.js:354:24)
    at Function.generate (/Users/alek/Desktop/pros/bs/node_modules/esdoc/out/src/ESDoc.js:149:10)
    at ESDocCLI.exec (/Users/alek/Desktop/pros/bs/node_modules/esdoc/out/src/ESDocCLI.js:71:23)
    at Object.<anonymous> (/Users/alek/Desktop/pros/bs/node_modules/esdoc/out/src/ESDocCLI.js:182:7)
    at Module._compile (module.js:573:30)
    at Object.Module._extensions..js (module.js:584:10)

error Command failed with exit code 1.

.esdoc.json:

{
  "source": "./src",
  "destination": "./docs",
  "plugins": [
    { "name": "esdoc-flow-type-plugin", "option": { "enable": true } },
    { "name": "esdoc-ecmascript-proposal-plugin", "option": { "all": true } },
    { "name": "esdoc-standard-plugin" }
  ]
}

esdoc: 1.0.3
esdoc-ecmascript-proposal-plugin: 1.0.0
esdoc-standard-plugin: 1.0.0
esdoc-flow-type-plugin 1.0.1

Redirect link from old Importpath Plugin goes to wrong URL

The URL from https://github.com/esdoc/esdoc-importpath-plugin currently goes to https://github.com/esdoc/esdoc-optional-plugins/tree/master/esdoc-importpath-plugin instead of https://github.com/esdoc/esdoc-plugins/tree/master/esdoc-importpath-plugin.

dev dependencies

It seems that some dependencies are out of date.

It might be worth checking them in general:

e.g. esdoc-publish-html-plugin

 cheerio                                         0.22.0  →  1.0.0-rc.2 
 fs-extra                                         1.0.0  →       5.0.0 
 babel-generator                                 6.11.4  →      6.26.1 
 marked                                           0.3.6  →      0.3.12 
 taffydb                                          2.7.2  →       2.7.3 
 babel-cli                                       6.11.4  →      6.26.0 
 babel-plugin-transform-es2015-modules-commonjs  6.11.5  →      6.26.0 
 babel-register                                  6.11.6  →      6.26.0 
 mocha                                            2.5.3  →       5.0.0

Marked < 3.7 has a vulnerability issue

Related to: #50

I personally use a service (bithound) to check for dependency health. It might be worth looking into that ;). Happy to help if you need any.

Typescript Plugin with Angular - Cannot avoid using @desc inside method headers

Short summary of your issue

If @desc is not explicitly used, and a description is provided in the first portion of the comment on a method, then both @param and @returns, are not documented inside of the output.

Input data for reproducing

{
  "destination": "./doc",
  "includes": [
    "\\.ts"
  ],
  "excludes": [
    ".*node_modules.*"
  ],
  "lint": false,
  "plugins": [
    {
      "name": "esdoc-standard-plugin",
      "option": {
        "coverage": {
          "enable": true
        }
      }
    },
    {
    	"name": "esdoc-typescript-plugin", 
    	"option": {
    		"enable": true
      }
    },
    {
      "name": "esdoc-plugin-require-coverage",
      "option": {
        "required": 0
      }
    }
  ]
}

Codes

/**
 * methodName - some description here
 * @param {object} param1 - description
 * @return {object} description 
 * @example example code here
 */
 methodName(param1: object): object {
     return {};
 }

Screen shot of documentation

Your environment

OS type and version: OS X El Capitan 10.11.6
Node.js version: 8.4.0
ESDoc version: 1.01

What does this plugin do?

Some documentation might help ...

Crash: esdoc-publish-html-plugin "SyntaxError: Invalid regular expression: /[~]function((string$/: Unterminated group"

SyntaxError: Invalid regular expression: /[~]function((string$/: Unterminated group
    at RegExp (<anonymous>)
    at SingleDocBuilder._findByName (.\one\node_modules\esdoc-publish-html-plugin\out\src\Builder\DocBuilder.js:116:20)
    at SingleDocBuilder._buildDocLinkHTML (.\one\node_modules\esdoc-publish-html-plugin\out\src\Builder\DocBuilder.js:768:22)
    at SingleDocBuilder._buildTypeDocLinkHTML (.\one\node_modules\esdoc-publish-html-plugin\out\src\Builder\DocBuilder.js:750:19)
    at ice.loop (.\one\node_modules\esdoc-publish-html-plugin\out\src\Builder\DocBuilder.js:896:29)
    at IceCap.loop (.\one\node_modules\ice-cap\out\src\IceCap.js:261:9)
    at SingleDocBuilder._buildProperties (.\one\node_modules\esdoc-publish-html-plugin\out\src\Builder\DocBuilder.js:887:9)
    at ice.loop (.\one\node_modules\esdoc-publish-html-plugin\out\src\Builder\DocBuilder.js:456:37)
    at IceCap.loop (.\one\node_modules\ice-cap\out\src\IceCap.js:261:9)
    at SingleDocBuilder._buildDetailDocs (.\one\node_modules\esdoc-publish-html-plugin\out\src\Builder\DocBuilder.js:409:9)

I think the ORIGINAL string is

...
 * @typedef {Object} SystemWriteStream
 * @property {function(string|ArrayBuffer):undefined} write
...

At that point name only is

function(string

So something got lost to begin with.

When I try a minimal @property {function(string)} write

SyntaxError: Invalid function type annotation: `function(string)`

Error source: https://github.com/esdoc/esdoc-plugins/blob/master/esdoc-publish-html-plugin/src/Builder/DocBuilder.js#L651

But that seems to be how you define function types??? Even WebStorm understands it, and I see that syntax recommended on StackOverflow, just one example of many: https://stackoverflow.com/a/38586423/544779

If you don't understand a syntax (bad enough), at the very least don't throw an error and stop EVERYTHING

This is a function syntax used by many, just one of numerous examples (not to mention that WebStorm would not have bothered to support this if that wasn't the case): https://stackoverflow.com/a/38586423/544779

Also, it should be supported at least through the Closure Compiler types, go to "Function Type": https://github.com/google/closure-compiler/wiki/Types-in-the-Closure-Type-System or https://github.com/google/closure-compiler/wiki/Annotating-Types#function-declarations or https://github.com/google/closure-compiler/wiki/Annotating-JavaScript-for-the-Closure-Compiler#function-type

eslint-publish-html with proposal decorators yields exception.

I have some issues with eslint-publish-html combined with esdoc-ecmascript-proposal-plugin and decorators feature.

When I combine those two i get this in the terminal:

Error: DocBuilder: can not resolve file name.
    at ClassDocBuilder._getOutputFileName (/SomePath/esdoc-publish-html-plugin/out/src/Builder/DocBuilder.js:613:15)
    at ClassDocBuilder._getURL (/SomePath/esdoc-publish-html-plugin/out/src/Builder/DocBuilder.js:573:29)
    at ClassDocBuilder._buildDocLinkHTML (/SomePath/esdoc-publish-html-plugin/out/src/Builder/DocBuilder.js:784:24)
    at ClassDocBuilder._buildTypeDocLinkHTML (/SomePath/esdoc-publish-html-plugin/out/src/Builder/DocBuilder.js:748:23)
    at ClassDocBuilder._buildSignatureHTML (/SomePath/esdoc-publish-html-plugin/out/src/Builder/DocBuilder.js:835:27)
    at ice.loop (/SomePath/esdoc-publish-html-plugin/out/src/Builder/DocBuilder.js:335:34)
    at IceCap.loop (/SomePath/ice-cap/out/src/IceCap.js:261:9)
    at ClassDocBuilder._buildSummaryDoc (/SomePath/esdoc-publish-html-plugin/out/src/Builder/DocBuilder.js:331:9)
    at ClassDocBuilder._buildSummaryHTML (/SomePath/esdoc-publish-html-plugin/out/src/Builder/DocBuilder.js:307:27)
    at ClassDocBuilder._buildClassDoc (/SomePath/esdoc-publish-html-plugin/out/src/Builder/ClassDocBuilder.js:115:36)

DocBuilder#_getOutputFileName laks of handling case where doc.kind == "index".

Any ideas why those two won't click?

(CSP) esdoc-publish-html-plugin: add a 'index.html.meta' file

To aid in Content Security Policy (CSP) usage by the generated output
When using a Apache webserver, you should add these lines in a file named "index.html.meta" and place it alongside the index.html file generated by esdoc"
(Alternatively you could also put it inside a "esdoc.meta" file somewhere else and link to it using correct names in-case it is needed by more than one file...)

Content-Security-Policy-Report-Only:
Content-Security-Policy:	default-src 'none';	script-src 'self' 'unsafe-inline';	style-src 'self' 'unsafe-inline' fonts.googleapis.com;	img-src 'self';	font-src 'self' fonts.gstatic.com;	report-uri /server-cgi/csp-violation;

The first line Content-Security-Policy-Report-Only: will disable your server-wide report-only policy if you are using Header setifempty Content-Security-Policy-Report-Only somewhere in the server configs, like i am.
You can skip it/remove it if you don't make use of that functionality.
The two domains mentioned in 2nd line, are ones used by the generated pages.
These two just happen to be the ones used by a default install of esdoc-standard-plugin / esdoc-publish-html-plugin
The report-uri /server-cgi/csp-violation; should point to your own script that collects csp-violations.
You can leave it as-is, to make your browser perform violation reporting. (The script can be an empty file also, just eliminate a 404 from Apache)

The values on the 2nd line could also be put inside the head of the html file with a <meta http-equiv="Content-Security-Policy" content="..."> tag, but you won't be allowed to use the reporting functionality in that case.
Besides the server-generated header will take precedence over the one inside a served document.
Anyway the file to modify would be between L4-L5 of esdoc-publish-html-plugin/out/src/Builder/template/layout.html
Hope this info will be useful to anyone 👍

manual publish with custom urls

Sequelize use manual publish with custom paths

"manual": {
    "globalIndex": true,
    "index": "./docs/index.md",
    "asset": "./docs/images",
    "badge": false,
    "installation": [
      "./docs/getting-started.md"
    ],
    "tutorial": [
      "./docs/models-definition.md",
      "./docs/models-usage.md",
      "./docs/querying.md",
      "./docs/instances.md",
      "./docs/associations.md",
      "./docs/transactions.md",
      "./docs/scopes.md",
      "./docs/hooks.md",
      "./docs/raw-queries.md",
      "./docs/migrations.md",
      "./docs/upgrade-to-v4.md"
    ],
    "advanced": [
      "./docs/legacy.md"
    ],
    "faq": [
      "./docs/whos-using.md",
      "./docs/imprint.md"
    ]

It looks like now there is only files options available. This means moving to v1 will break existing urls ? Is there any way to keep using old format ?

Typescript Plugins - <T> variable syntax causes parse error

Having a regular TypeScript cast e.g. <FormControl> element inside a .ts file causes the parser to throw a syntax error and the entire documentation generation halts.

Show list of methods in the navigation pane?

We are currently looking at switching to esdoc and it looks great. My one question is - how do we get it to display a list of methods in the navigation menu on the left when looking at a particular class? It's hard to get an overview and navigate within a large class.

I've looked through the source for esdoc-publish-html-plugin but I couldn't find any options. Is this something that could be implemented?

Thanks.

ESDoc Standard Plugin should have the required other plugins as dependencies

I tried esdoc out today and had to manually install all these plugins, after installied esdoc-standard-plugin:

esdoc-lint-plugin
esdoc-coverage-plugin
esdoc-accessor-plugin
esdoc-type-inference-plugin
esdoc-external-ecmascript-plugin
esdoc-brand-plugin
esdoc-undocumented-identifier-plugin
esdoc-unexported-identifier-plugin
esdoc-integrate-manual-plugin
esdoc-integrate-test-plugin
esdoc-publish-html-plugin

Since these are hard dependencies, they should be under the dependencies in the package.json.

esdoc-importpath-plugin 0.1.1 to 0.1.3 is a breaking change

It looks like esdoc-importpath-plugin v0.1.1 expects to be working with esdoc v0.5.2. The plugin's current active version is 0.1.3 which looks like it expects to work with 1.0.0-alpha.7 which is not automatically installed. Running npm install esdoc esdoc-importpath-plugin will pull in versions v0.5.2 and v0.1.3 which don't work together. Versions v0.1.2 and v0.1.3 of the plugin should probably be deprecated and will have to make sure they aren't pulled automatically when you install esdoc-importpath-plugin@^0.1 and the breaking version could probably be republished as v0.2.x-alpha.1 under the alpha tag.

duplicate IDs in CHANGELOG.md

If the Changelog contains same name headlines e.g. "Big Fixes" The HTML has duplicate IDs in the content and sidebar.

Esdoc: https://sinnerschrader.github.io/esdoc-custom-theme/manual/CHANGELOG.html#bug-fixes

Github: https://github.com/sinnerschrader/esdoc-custom-theme/blob/master/CHANGELOG.md#bug-fixes-1

Interfaces don't work on esdoc-typescript-plugin

Using esdoc-typescript-plugin the plugin throws exceptions when trying to parse a typescript file containing an interface. The error specifically says "interface is a reserved word in strict mode"
See attachments:
Error.txt

LoginForm.txt

Eslint Configuration:

{
"source": "./src",
"includes": ["\\.tsx?$"],
"destination": "./docs",
"plugins": [
{
"name": "esdoc-standard-plugin",
"test": {
"source": "./__tests__",
"includes": ["\\.(test|Test|spec|Spec)\\.tsx?$"]
},
"coverage": { "enable": true },
"undocumentIdentifier": { "enable": true },
"unexportIdentifier": { "enable": true }
},
{ "name": "esdoc-typescript-plugin"},
{ "name": "esdoc-jsx-plugin"},
{"name": "esdoc-react-plugin"}
]
}

Manual overwrite filenames when two file has the same name

Consider the following config:

{
  "source": "./",
  "destination": "./docs",
  "plugins": [{
    "name": "esdoc-standard-plugin",
    "option": {
      "manual": {
        "index": "./API.md",
        "files": [
          "./foo/README.md",
          "./bar/README.md"
        ]
      }
    }
  }]
}

The following config will generate the same file ./manual/README.md twice and therefore will overwrite each other.

Empty string as default is resolved as undefined

I have following class:
class LocalStorage { constructor(prefix: string = '') { } }

ESdocs will describe it as:

prefix | string | optional, default: undefined

But default is not undefined, it is empty string.

When I try
class LocalStorage { constructor(prefix: string = 'x') { } }

Results is
prefix | string | optional, default: x

Which is ok. Problem is only in empty string. My config is:

{
  "source": "./src",
  "destination": "./docs",
  "excludes": ["index.js"],
  "plugins": [
    {
      "name": "esdoc-standard-plugin"
    },
    {"name": "esdoc-flow-type-plugin", "option": {"enable": true}},
    {"name": "esdoc-ecmascript-proposal-plugin", "option": {"all": true}}
  ]
}

Publish-html-plugin template not working with standard-plugin

Hello !
esdoc-standard-plugin isn't taking the template option into account the way the stand-alone esdoc-publish-html-plugin does.
In fact, we can see in plugin.js that no option is passed to the plugin when using esdoc-standard-plugin :

class Plugin {
  onHandlePlugins(ev) {
    const option = ev.data.option || {};
    const plugins = [
      {name: 'esdoc-lint-plugin', option: option.lint},
      {name: 'esdoc-coverage-plugin', option: option.coverage},
      {name: 'esdoc-accessor-plugin', option: option.accessor},
      {name: 'esdoc-type-inference-plugin', option: option.typeInference},
      {name: 'esdoc-external-ecmascript-plugin'},
      {name: 'esdoc-brand-plugin', option: option.brand},
      {name: 'esdoc-undocumented-identifier-plugin', option: option.undocumentIdentifier},
      {name: 'esdoc-unexported-identifier-plugin', option: option.unexportedIdentifier},
      {name: 'esdoc-integrate-manual-plugin', option: option.manual},
      {name: 'esdoc-integrate-test-plugin', option: option.test},
      {name: 'esdoc-publish-html-plugin'}
    ];

    const existPluginNames = ev.data.plugins.map(plugin => plugin.name);
    for (const plugin of plugins) {
      if (existPluginNames.includes(plugin.name)) continue;
      if (plugin.option === undefined) delete plugin.option;
      ev.data.plugins.push(plugin);
    }
  }
}

module.exports = new Plugin();

I tried replacing the faulty line with {name: 'esdoc-publish-html-plugin', option: option.template} as a potential trivial fix that it didn't do the trick. (template isn't used)

Currently, I have to import the esdoc-publish-html-plugin separately but this implies minor incompatibility issues between the plugins (coverage rates not showing up in the Source page when using a template).

Thanks for helping !

Only json output

Does the "esdoc-ecmascript-proposal-plugin" plugin intentionally only generate json output (index.json and the 'ast' folder) or am I missing something?
My config (same as in the readme):

{
  "source": "./src",
  "destination": "./doc",
  "plugins": [
      {"name": "esdoc-ecmascript-proposal-plugin", "option": {"all": true}}
   ]
}

ECMAScript proposals error

Error:

warning: could not parse the following code. if you want to use ECMAScript proposals, see https://esdoc.org/manual/feature.html#ecmascript-proposal

Config:

{
  "source": "./src",
  "destination": "./docs",
  "plugins": [
    {
      "name": "esdoc-standard-plugin"
    },
    {
      "name": "esdoc-ecmascript-proposal-plugin",
      "option": {
        "all": true
      }
    }
  ]
}

ESDoc fails on:

const obj = {
    to: options.to,
    opts: {
        html: true,
        ...options
    }
}

Or (in generated docs only PORT is visible):

export const {
  PORT,
  JWT
} = process.env;

esdoc-typescript-plugin hits error

Cannot find module 'esdoc/out/src/Parser/CommentParser'
occured in ..node_modules/esdoc-typescript-plugin/src/index.js:3:68

esdoc-publish-html-plugin includes non-configurable "class" directory for classes

This is a problem when using Jenkins as a CI tool; its "Publish Javadoc" post-build action results in code being served by Jetty, which silently filters out paths with a class part. To work around this, I've needed to include this horrible hacky monkeypatching "plugin" in my ESDoc configuration:

const DocBuilder = require('esdoc-publish-html-plugin/out/src/Builder/DocBuilder').default;

if (!DocBuilder.prototype.__gOFN) {
  DocBuilder.prototype.__gOFN = DocBuilder.prototype._getOutputFileName;
  DocBuilder.prototype._getOutputFileName = function (doc) {
    return this.__gOFN(doc).replace(/^class\//, 'cls/');
  };
}

module.exports = {}

Any ideas for a cleaner solution? Jenkins in this case is in a hosted environment and is not configurable at the required level to fix this there.

esdoc-publish-markdown-plugin - config missing

Hi! I think this plugin will come in handy for GitBook integration. However, it is not configurable at the moment. I have provided the same options to esdoc-standard-plugin and esdoc-publish-markdown-plugin. The standard plugin works, but the markdown plugin includes private properties

.esdoc.json

{
    "source": "./src/main/js",
    "destination": "./docs",
    "plugins": [
        {
            "name": "esdoc-standard-plugin"
        ,   "option": {
                "accessor": {
                    "access": ["public"]
                ,   "autoPrivate": true
                }
            }
        }
    ,
        {
            "name": "esdoc-publish-markdown-plugin"
        ,   "option": {
                "accessor": {
                    "access": ["public"]
                ,   "autoPrivate": true
                }
            }
        }
    ]
}

mock source file

import { Model } from "app/mvc/model/Model"
import { View } from "app/mvc/view/View"

export class Controller {

    /**
     * Create a new Controller.
     *
     * @param {Model} [model=new Model] A Model
     * @param {View} [view=new View] A View
     * @constructor
     * @see {@link Controller#setModel}
     * @see {@link Controller#setView}
     */
    constructor (model = new Model, view = new View) {
        console.info(new.target.name)
        this.setModel(model)
        this.setView(view)
    }

    /**
     * Set the Controller Model
     * @param {Model} model A model
     * @return {void}
     * @see {@link Controller#getModel}
     */
    setModel (model) {
        console.info(`Controller#setModel(View):void`)
        model.setController(this)
        /** @private */
        this._model = model
    }

    /**
     * Get the Controller Model
     * @return {Model}
     * @see {@link Controller#setModel}
     */
    getModel () {
        return this._model
    }

    /**
     * Set the Controller View
     * @param {View} view A View
     * @return {void}
     * @see {@link Controller#getView}
     */
    setView (view) {
        console.info(`Controller#setView(View):void`)
        view.setController(this)
        /** @private */
        this._view = view
    }

    /**
     * Get the Controller View.
     * @return {View}
     * @see {@link Controller#setView}
     */
    getView () {
        return this._view
    }
}

Output from esdoc-publish-markdown-plugin:

`Controller`

`constructor(model: Model, view: View)`

Create a new Controller.

`_model: *`

`_view: *`

`setModel(model: Model): void`

Set the Controller Model

Name	Type	Attribute	Description
model	Model		A model

`getModel(): Model`

Get the Controller Model

Name	Type	Attribute	Description

`setView(view: View): void`

Set the Controller View

Name	Type	Attribute	Description
view	View		A View

`getView(): View`

Get the Controller View.

Name	Type	Attribute	Description

I'm surprised that _model:* and _view:* were included as option.accessor.autoPrivate was set to true.

I can see that this plugin is POC, but its a good one!

It would be great if

you could provide a path to a custom template (for custom MD formatting)
assign the same standard-esdoc-plugin options

        {
            "name": "esdoc-publish-markdown-plugin"
        ,   "option": {
                "accessor": {
                    "access": ["public"]
                ,   "autoPrivate": true
                }
            ,  "template": "./src/manual/template/publish-template.md"
            }
        }

What do you think?

Structural and style inconsistencies

I set out to create a custom style sheet, because, though esdoc does make quite beautiful docs (jolly well done everyone) I do find it a bit difficult to pick stuff out of the mass of black and grey similarly indented similar spaced blurb...

I've run into difficulties though, I did create a style sheet I felt improved things a lot, but it's kinda nasty, it matches based on things I really feel it shouldn't, and on stuff I feel might reasonably change, and I couldn't do everything I wanted...

The thing is, the content produced doesn't really have (for example) an element with a class of (say) "class", in which a class is rendered with more child elements with classes of (say) "method" and "parameter", etc. So the capability to (say) select all headers in a class render and make them some colour, or all 'details' sections in a variable render and indent them a certain amount... is just a nightmare.

Changing this and making it more consistent and easy to style isn't necessarily very difficult, but to do so properly and retain backwards compatibility seems impossible to me.. so I thought I'd raise the issue and see what prevailing opinions were...

Documentation index removed by external-nodejs plugin

The documentation index (config.index) is removed by the external plugin.

The error occurs at line:
https://github.com/esdoc/esdoc-plugins/blob/master/esdoc-external-nodejs-plugin/src/Plugin.js#L30

This problem only occurs when the README.md is inside (a subdirectory of) config.source and config.includes is specified. But I have to do this as there is currently no way to provide an array of source directories.

That's all the debugging for tonight. I don't know if I'll have time to debug this further this weekend. But I should find some time next week.

Undecipherable error message in esdoc-publish-html-plugin

I keep running into this error while using the esdoc-publish-html-plugin plugin. Would it be possible to throw a more sensible error. Would be nice to see, for example, in which file the error occurred.

TypeError: Cannot read property 'replace' of undefined
  at inner.split.map.v (c:\code\node_modules\esdoc-publish-html-plugin\out\src\Builder\DocBuilder.js:702:30)
  at Array.map (<anonymous>:null:null)
  at ClassDocBuilder._buildTypeDocLinkHTML (c:\code\node_modules\esdoc-publish-html-plugin\out\src\Builder\DocBuilder.js:699:43)
  at v.split.map.vv (c:\code\node_modules\esdoc-publish-html-plugin\out\src\Builder\DocBuilder.js:729:23)
  at Array.map (<anonymous>:null:null)
  at inner.split.map.v (c:\code\node_modules\esdoc-publish-html-plugin\out\src\Builder\DocBuilder.js:727:29)
  at Array.map (<anonymous>:null:null)
  at ClassDocBuilder._buildTypeDocLinkHTML (c:\code\node_modules\esdoc-publish-html-plugin\out\src\Builder\DocBuilder.js:726:43)
  at ice.loop (c:\code\node_modules\esdoc-publish-html-plugin\out\src\Builder\DocBuilder.js:896:29)
  at IceCap.loop (c:\code\node_modules\ice-cap\out\src\IceCap.js:261:9)
  at ClassDocBuilder._buildProperties (c:\code\node_modules\esdoc-publish-html-plugin\out\src\Builder\DocBuilder.js:887:9)
  at ice.loop (c:\code\node_modules\esdoc-publish-html-plugin\out\src\Builder\DocBuilder.js:454:37)
  at IceCap.loop (c:\code\node_modules\ice-cap\out\src\IceCap.js:261:9)
  at ClassDocBuilder._buildDetailDocs (c:\code\node_modules\esdoc-publish-html-plugin\out\src\Builder\DocBuilder.js:409:9)
  at ClassDocBuilder._buildDetailHTML (c:\code\node_modules\esdoc-publish-html-plugin\out\src\Builder\DocBuilder.js:388:27)
  at ClassDocBuilder._buildClassDoc (c:\code\node_modules\esdoc-publish-html-plugin\out\src\Builder\ClassDocBuilder.js:122:41)
  at ClassDocBuilder.exec (c:\code\node_modules\esdoc-publish-html-plugin\out\src\Builder\ClassDocBuilder.js:31:32)
  at Plugin._exec (c:\code\node_modules\esdoc-publish-html-plugin\out\src\Plugin.js:93:63)
  at Plugin.onPublish (c:\code\node_modules\esdoc-publish-html-plugin\out\src\Plugin.js:71:10)
  at Plugin._execHandler (c:\code\node_modules\esdoc\out\src\Plugin\Plugin.js:55:26)
  at Plugin.onPublish (c:\code\node_modules\esdoc\out\src\Plugin\Plugin.js:154:10)
  at Function._publish (c:\code\node_modules\esdoc\out\src\ESDoc.js:354:24)
  at Function.generate (c:\code\node_modules\esdoc\out\src\ESDoc.js:149:10)

How does Typescript ESDoc measure comment coverage?

I am writing in Angular4 and Typescript with the esdoc-coverage-plugin and esdoc-typescript-plugin.

In my codebase, every method, class, and member have a comment block in this form:
/** @method methodName
* @desc method description
* @param {type} paramName - description of paramName
* @returns {type}
*/
methodName(param: type) {
/** the if statement does this */
if(something) { doSomething(); } else { doSomethingElse(); } }

Some files reach 100% with this format, other files are stuck at 40%. Even after putting in placeholder comments above each line of code, even documenting each if-else branch in detail, I cannot raise the coverage. What am I missing?

I cannot provide a physical snippet of the code, but I can try and answer any follow up questions you have if you need more information to give me an answer, thank you.