While the JSDoc project pioneered the generation of JS API references, documentation.js seems to be maintained more frequently, and also offers support for ES6+ code syntax.

as some tests really interact with github, timeouts happen pretty often and lead to failing tests. re-running "fixes" them, but this is very inconvenient.

options:

• stub the tests which really call to github
• disable them for travis (using env)
• stub them only for travis

https://doclets.io/BoolJS/booljs-api/master

api tree incomplete e.g. removeInstance not in tree

url is : https://doclets.io/sync
response is : Err {"message":"Bad credentials","documentation_url":"https://developer.github.com/v3"}

I tried to log out and revoke Doclets authorization from my github account, but this didn't seen to work.

Hi,

This might seem a bit far-fetched, but just in case... wouldn't it be nice to be able to specify for documentation files that do not belong to the immediate repository (remote files)?

Possible use cases:

1. documenting dependencies that don't have their own documentation;
2. creating a centralized documentation for a modularized library without loading/duplicating all libraries in the central repository.

Another way of solving the second scenario would be for doclets.io to allow creating a centralized entry point for docs generated for each module, but IMO that would a lot harder to implement than just loading remote files, which also solves the first scenario.

doclets with many playgrounds get stuck, because of pretty slow load times of the playgrounds supported by the awesome tonicdev.

example:
https://doclets.io/dleitee/strman/master

how can this be solved? the main focus should be to allow to user to scroll the page, even if not all playgrounds are loaded. this is the code which loads / embeds the playgrounds:

https://github.com/lipp/doclets/blob/master/views/doclayout.jade#L36

Doclets looks really promising. Will it stay free for open source projects once beta phase is over?

For some reason doclets (https://doclets.io/the-letter-e-production/Express-MVC/add-to-doclets) is not picking up the follwing file:
https://github.com/the-letter-e-production/Express-MVC/blob/add-to-doclets/lib/Router.js

Any idea why this is happening?

When using @seelike this:

...
   * @see [finders/genericAnchors.js]{@link
   * https://github.com/crawlkit/crawlkit/blob/master/finders/genericAnchors.js}
   * for an example of a valid returned runnable function.
...

The result is only partially correct:

Hi,

Thanks a lot for doclets! Finally looks like a way to make the value of documentation more tangible :)

I had a surprise when trying to add it to Watai, though: some classes are not parsed properly, and their methods are parsed as globals.
It seems to me the issue is related to the @lends syntax.

Example: result and source.

Cheers,
Matti

I'm trying to login and try Doclets. I get to the GitHub authorization screen but when I click authorize I'm redirected to https://doclets.io/auth/github/callback?code=%hexstring%

And get the following error:

TypeError: req.session.save is not a function
   at Routes.authGithubCallback (/usr/src/app/lib/routes.js:15:15)
   at Layer.handle [as handle_request] (/usr/src/app/node_modules/express/lib/router/layer.js:95:5)
   at next (/usr/src/app/node_modules/express/lib/router/route.js:131:13)
   at complete (/usr/src/app/node_modules/passport/lib/middleware/authenticate.js:250:13)
   at /usr/src/app/node_modules/passport/lib/middleware/authenticate.js:257:15
   at pass (/usr/src/app/node_modules/passport/lib/authenticator.js:421:14)
   at Authenticator.transformAuthInfo (/usr/src/app/node_modules/passport/lib/authenticator.js:443:5)
   at /usr/src/app/node_modules/passport/lib/middleware/authenticate.js:254:22
   at /usr/src/app/node_modules/passport/lib/http/request.js:60:7
   at pass (/usr/src/app/node_modules/passport/lib/authenticator.js:267:43)
   at serialized (/usr/src/app/node_modules/passport/lib/authenticator.js:276:7)
   at /usr/src/app/lib/routes.js:394:9
   at model.<anonymous> (/usr/src/app/node_modules/mongoose/lib/document.js:1842:20)
   at next_ (/usr/src/app/node_modules/mongoose/node_modules/hooks-fixed/hooks.js:89:34)
   at fnWrapper (/usr/src/app/node_modules/mongoose/node_modules/hooks-fixed/hooks.js:186:18)
   at /usr/src/app/node_modules/mongoose/lib/model.js:292:13

We use the @class tag to give a general description of the class, and @constructor to describe its specific arguments - However, the class members are shown for both

https://doclets.io/janmeier/sequelize/janmaster#dl-Sequelize

I think that if @class is defined, @constructor should not show the members

I have added my repository to doclets (https://github.com/mtrevisan/library), added the .doclets.yml accordingly (https://github.com/mtrevisan/library/blob/dev/.doclets.yml), and then it landed me to this page: https://doclets.io/mtrevisan/library/dev, giving me the following error:

`TypeError: /usr/src/app/views/doclayout.jade:19
17| ul.args
18| if func.params
19| each param in _.filter(func.params, function(param) {return param.name.indexOf('.') === -1;})
20| li(class=param.optional ? 'optional' : undefined)= param.name
21| if !isCtor && func.returns && func.returns[0] && func.returns[0].type
22| - var names = _.map(func.returns[0].type.names, tools.shortName);

Cannot read property 'indexOf' of undefined
at eval (eval at (/usr/src/app/node_modules/jade/lib/index.js:218:8), :1645:71)
at /usr/src/app/node_modules/underscore/underscore.js:227:11
at Function..each..forEach (/usr/src/app/node_modules/underscore/underscore.js:153:9)
at Function..filter..select (/usr/src/app/node_modules/underscore/underscore.js:226:7)
at Object.eval (eval at (/usr/src/app/node_modules/jade/lib/index.js:218:8), :1645:17)
at Object.jade_mixins.funcdeclx.jade_interp [as funcdeclx](eval at %28/usr/src/app/node_modules/jade/lib/index.js:218:8%29, :1677:4)
at Object.jade_mixins.title.jade_interp [as title](eval at %28/usr/src/app/node_modules/jade/lib/index.js:218:8%29, :3654:25)
at Object.jade_mixins.doclet.jade_interp [as doclet](eval at %28/usr/src/app/node_modules/jade/lib/index.js:218:8%29, :4468:21)
at eval (eval at (/usr/src/app/node_modules/jade/lib/index.js:218:8), :4574:22)
at eval (eval at (/usr/src/app/node_modules/jade/lib/index.js:218:8), :4599:4)
at eval (eval at (/usr/src/app/node_modules/jade/lib/index.js:218:8), :4760:22)
at res (/usr/src/app/node_modules/jade/lib/index.js:219:38)
at Object.exports.renderFile (/usr/src/app/node_modules/jade/lib/index.js:380:38)
at Object.exports.renderFile (/usr/src/app/node_modules/jade/lib/index.js:370:21)
at View.exports.__express as engine
at View.render (/usr/src/app/node_modules/express/lib/view.js:126:8)`

A type definition like:

@type {!Object.<String,String>}

is transformed incorrectly to:

All three types should be linked independently (in the case of Object, String and * probably no link, as they are base types).
Also, the preceding ! (non-null indicator) seems to be discarded and not to appear in the docs anywhere.

add some info to the readme to enable contributors to locally develop and test

Sorry, something went wrong during creation of your doclet!
Error: Error: ENOENT: no such file or directory, open '/usr/src/app/lib/031eafb0-dbe3-11e5-9d55-ed04cc93f6aa'

As shown on my page for the repo/branch. This is the first time I've pushed to this branch with a .doclets.yml

The config I used was quite simple:

dir: lib
packageJson: package.json

Some inconsistency in the docs regarding the doclet config, but I'll create a separate issue.

Edit: To note, I've declared all of the documentation in this repository out of context (it's not inline with other code, only jsdocs code is in the repo) and I'm declaring it within .coffee files, not .js.

A branch named feature/doclets will cause a Err null result

See https://doclets.io/openzero-zte/js-generator-openstack/feature/doclets

a JSDoc annotation like this:

  /**
   * @ignore
   */
  some symbol

should exclude the following symbol from showing up in the documentation.

I got a couple of helper functions, which are exported as default. Since I have quite a few of them, they only show up as module/exports() in the list.

Let's take this example. This is how my code looks like:

**
 * Creates an HTML template string and returns it.
 * @see Code taken from https://hacks.mozilla.org/2015/05/es6-in-depth-template-strings-2/
 * @param {String} template - The HTML string written in template strings
 * @return {String} result - The new string
 */
export default function HTML (template) {
 // ...
}

The output in Doclets is like this, among many other module/exports:

This makes it very unorganised and hard to find a function.
Is it possible to display the function.name instead? In my previous example it could be like module/HTML or similar.

Hello,

I have the following type definition

/**
 * The database type.
 * @typedef {Object} DB
 * @property {String} folder - The path of the folder where the data files are stored.
 * @property {Object<String, Schema>} schemas - The schemas on the database.
 */

The type DB is shown on the documentation but the properties folder and schemas are shown without types. Is there any way to show types for these like shown for function arguments for exemple ?

Thank you,
Amine

Hi,

Are you planning to support JSDoc plugins?

For example https://doclets.io/sequelize/sequelize/doclets#dl-Model

Since this class has a lot of members, it would be nice to be able to clearly see which are instance and which are static

Hello 👋,

it looks like the documentation is broken once a JSDoc comment has incorrect formatting.
Here are two occurrences I found:

• If you go to this part of my documentation, you see that it stops reporting in the middle of the sentence. I assume the chevron (<atom-styles>) in my description causes this problem?
  
• The documentation for my createElement() method also stops with the description, and everything after that is left blank on the page. I also guess it's because I used probably unknown formatting of an optional parameter which also happens to accept two different types: @param {(Number|String)}.
  

This makes me also think what the correct declaration of an optional parameter is, which happens to accept multiple types.

Anyway, great work! Really like this project 😀

Best,
Moritz

node-github introduced some API changes (see #132 )

The build for the following Webpack compiled project failed:

https://doclets.io/tf/pageflow-react/add-to-doclets

It contains both ES2015 code and JSX files. Is support for those features planned? JSDoc claims to support it.

Is there any way to add repos from an organization? Would be amazing!

I'm trying to progressively add documentation to my repository over at https://github.com/YoloDev/nitter using the add-to-doclets branch. However, doclets.io stopped showing my changes after a few updates, and now I can't seem to get it to work again. I've even tried deleting and recreating the branch, but it doesn't work. Please help.

At the moment, members of classes defined with an .extends({...}) pattern get listed as part of the global scope. Having to put a @memberof tag on all members would be a lot of bloat. Is there an alternative? This might also be the wrong repo to ask this question since it might simply be a general JSDoc issue?

link to https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement

Hi there, I was wondering if there were any plans to add support for private repos

I am not sure what's wrong. In the list I see badge that says failed, but I cannot seem to find any details anywhere about failure.

https://doclets.io/BlackDice/b3-chief/master

The doclets.yml look like this

dir: src

packageJson: package.json

articles:

  - Overview: README.md

branches:

  - master

Regarding information at: https://doclets.io/doclets.yml

lib/dir declaration:

Image seems to show and describe a "dir" option with "lib" parameter.

Example 3 shows the same.

Explanation shows a "lib" option, but no "dir" option.

Using doclets on any files whose paths contain spaces will not work. This is because file paths are not surrounded by quotes when passed to the jsdoc interpreter.

I tried to signup and when coming back from GitHub OAuth I got a 504 Gateway Timeout.

Now I can't login, anytime I login or try to go to my account I get a 504 Gateway Timeout.

Am I doing something wrong?

https://doclets.io/carrot/roots-mini/master

should work like this:

$ npm install doclets -g
$ cd your-project
$ doclets preview 8090

this will start a webserver on localhost:8090 which shows the output doclets.io would generate

@link tags in JSDoc seems to be ignored, e.g.:

{@link MyClass#method}

or

[PhantomJS spec]{@link http://phantomjs.org/api/webpage/method/add-cookie.html}

Currently nested and top-level parameters are rendered in a single list - which can become very long, see below

Which is generated from https://github.com/sequelize/sequelize/blob/35e68f67b9be2702109157b6d066781555d43202/lib/model.js#L1314-L1344

Regular jsdoc shows this as a nested table, but keeping with the doclets list structure we could go for nested lists instead - note that I also removed the options. prefix in order to take up less space

It's still hella-long, but at least it's a bit easier to see what goes where - I also made the margins on the nested lists a bit smaller :)

Any plans or chance for support of other source other than github? I personally use gitlab (both a community server that I maintain, as well as sometimes using gitlab.com) and it'd be great to be able to gather from those sources.

If auth integration dev is a concern, perhaps a more simple approach could be used by providing an https url for a repo, as well as a username and password to access it, or a deploy key.

For example, see these generated docs: https://doclets.io/trusktr/awaitbox/master

Then, look in the src folder of the repo: https://github.com/trusktr/awaitbox

Any tips on what to do?

Hitting https://doclets.io/sync shows:

Err {"message":"Bad credentials","documentation_url":"https://developer.github.com/v3"}

I believe that happened, because of the following steps:

• Login to doclets.io, granting access
• Revoking the access for doclets.io on the github side (I did that because organization repos weren't showing up before knowing it was due to #50)
• Logging in to doclets.io again, granting access again
• Clicking the Re-Sync Repositories button.

as @tf
https://doclets.io/tf

The branch filter seems to be ignored when restarting the server and event catchup happens...

Support the non-standard but commonly used @category tag for grouping related stuff.

It looks like the value of the @since tag is currently not visible in the generated doc. I always find it nice to see since when a certain feature is present.

Example: https://doclets.io/tf/pageflow/add-to-doclets#dl-pageflow-Features

Feature idea: Add an option to .doclets.yml that enables automatically building documentation for all pull requests. That way it's always easy to check whether documentation changes made by PRs are valid and complete. There could be an extra section in the project's page on doclets.io listing recent PRs.

Cherry on top: Integrate with GitHub status API to display build success/failure and link to output.

Show warning / errors during JSDoc generation. This will help the user figure out what's going on (e.g. something missing see #75).
Maybe on user/repo view (dashboard)

as suggested by @joscha

what about allowing custom tags and a widget definition for it - that way I could add a

@tonicdev src/bla/example22.js

that gets rendered like a playground and a

@jsfiddle src/browser/example54.js src/browser/file.css

that gets rendered in jsFiddle style based on what the widget thinks is best.

I get the error:

Error: TypeError: Path must be a string. Received [ 'src', 'finders' ]

but my project has source files that are both in src and finders. I propose dir should be able to accept multipel values.