jsdoc2md / jsdoc-to-markdown Goto Github PK

My Event

/**
 * Snowball event.
 *
 * @event Hurl#snowball
 * @type {object}
 * @property {boolean} isPacked - Indicates whether the snowball is tightly packed.
 */

Generates:

<a name="Hurl#event_snowball"></a>
##event: "snowball"
Snowball event.

**Type**: `object`

I would expect my properties to be listed.

It looks like that @this is not supported. Please see http://usejsdoc.org/tags-this.html

/**
 * Do something.
 *
 * @param  {String}   [task=foo]  The task to do
 */
function foo(task) {
}

The above example does not highlight the default value of the task argument, which would be cool.
Am I missing something or simply there's no highlighting for it?

This tool is fantastic. I love it already. However, I have a couple classes with constructors I'd consider "private". I want to exclude them from documentation since they shouldn't be called by the user. If I mark the constructor documentation with @Private, however, it treats the whole class as private and ignores it.

Is there anyway to ignore a constructor?

Is something like this possible with the command line? Or do I have to use the node api?

jsdoc2md ./*.js > ./docs/*.md

Are command line arguments supposed to be trailing? The help states options then source, but that order causes the program to hang. When using trailing options, everything works fine. (ex jsdoc2md scoure.js --plugin dmd-bitbucket)

I've been wrestling a lot with markdown and jsdoc in general. I'm interested in some extra functionality that jsdoc2md doesn't (to my knowledge) provide.

The project by @thlorenz thlorenz/doctoc adds a table of contents to an existing document. It's in that module's nature to need an existing doc, so it supports this comment syntax

<!-- START doctoc -->
<!-- END doctoc -->

And if it finds it in the markdown, it replaces it with the TOC something like this:

<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->

... stuff

<!-- END doctoc generated TOC please keep comment here to allow auto update -->

This is ideal because if I run the command again to update it preserves my original file and updates the TOC.

I need this same support for jsdoc2md. Is this something this module can support? Already does support?

Understandably it's not necessary to the functionally to update an existing doc, it just overwrites.

@75lb Interested in your thoughts on supporting a comment block.

Hi,

I'm completely satisfied with this module which handles everything I need.
However when using this syntax:

/**
 * @param {(string|Number)} data
 */

It turns into <code>string</code> \| <code>Number</code> which seems to not be supported as standard markdown. It is here in github though. But usually it results into defining another column in the output table.

Would it be possible to output the ascii code:

|

instead of \| ?

Since | has no "markdown" meaning here, it should not break anything.

Hi, for a bigger example of jsdoc-to-markdown you may like to showcase https://github.com/resin-io/resin-sdk.

There is a DOCUMENTATION.md file (https://github.com/resin-io/resin-sdk/blob/master/DOCUMENTATION.md) being generated with jsdoc-to-markdown.

The error I got when running jsdoc2md({ src: source }).pipe(fs.createWriteStream(output));

WARNING: JSDoc does not currently handle ExportDefaultDeclaration nodes. Source file: /Users/Alex/Projects/pixi-cli-server/plugins/class/0.0.1.js, line 102
events.js:85
      throw er; // Unhandled 'error' event
            ^
TypeError: Cannot read property 'match' of undefined
    at Object.parseType (/Users/Alex/Projects/pixi-cli-server/node_modules/jsdoc-to-markdown/node_modules/dmd/helpers/helpers.js:260:25)
    at Object.eval (eval at <anonymous> (/Users/Alex/Projects/pixi-cli-server/node_modules/jsdoc-to-markdown/node_modules/dmd/node_modules/stream-handlebars/node_modules/handlebars/dist/cjs/handlebars/compiler/javascript-compiler.js:209:23), <anonymous>:8:108)
    at prog (/Users/Alex/Projects/pixi-cli-server/node_modules/jsdoc-to-markdown/node_modules/dmd/node_modules/stream-handlebars/node_modules/handlebars/dist/cjs/handlebars/runtime.js:178:15)
    at execIteration (/Users/Alex/Projects/pixi-cli-server/node_modules/jsdoc-to-markdown/node_modules/dmd/node_modules/stream-handlebars/node_modules/handlebars/dist/cjs/handlebars/base.js:133:19)
    at Object.<anonymous> (/Users/Alex/Projects/pixi-cli-server/node_modules/jsdoc-to-markdown/node_modules/dmd/node_modules/stream-handlebars/node_modules/handlebars/dist/cjs/handlebars/base.js:142:11)
    at Object.eval (eval at <anonymous> (/Users/Alex/Projects/pixi-cli-server/node_modules/jsdoc-to-markdown/node_modules/dmd/node_modules/stream-handlebars/node_modules/handlebars/dist/cjs/handlebars/compiler/javascript-compiler.js:209:23), <anonymous>:5:34)
    at Object.prog [as fn] (/Users/Alex/Projects/pixi-cli-server/node_modules/jsdoc-to-markdown/node_modules/dmd/node_modules/stream-handlebars/node_modules/handlebars/dist/cjs/handlebars/runtime.js:178:15)
    at Object.<anonymous> (/Users/Alex/Projects/pixi-cli-server/node_modules/jsdoc-to-markdown/node_modules/dmd/node_modules/stream-handlebars/node_modules/handlebars/dist/cjs/handlebars/base.js:181:22)
    at Object.eval (eval at <anonymous> (/Users/Alex/Projects/pixi-cli-server/node_modules/jsdoc-to-markdown/node_modules/dmd/node_modules/stream-handlebars/node_modules/handlebars/dist/cjs/handlebars/compiler/javascript-compiler.js:209:23), <anonymous>:5:35)
    at ret (/Users/Alex/Projects/pixi-cli-server/node_modules/jsdoc-to-markdown/node_modules/dmd/node_modules/stream-handlebars/node_modules/handlebars/dist/cjs/handlebars/runtime.js:144:30)

This happens when there's a jdoc property @priate instead of @private

Is there a way to enable Github source code linking like Dokker does?

jsdoc allows to pass config path like this:

jsdoc www -r -c \"jsdoc2md/conf.json\" -d docs

Is there a way to do this with jsdoc-to-markdown (so that @partial plugin can be used for example)?

For some reason the class instance names have last letter capitalized in my docs, e.g.

new API() <-- correct
apI.shutdown() <-- every API method is like this

Here are the generated markdown docs. Notice how the Utils class is capitalized correctly.

Kudos on the project!

I noticed the following behavior when trying to use the @see tag to link to another method in a module named util.

Input:

@see {@link util.myMethod} some descriptive text

Actual Output:

[util.myMethod](util.myMethod) some descriptive text

Expected output:

[util.myMethod](#module_util.myMethod) some descriptive text

To reproduce:

/** @module util */

/**
 * Always returns true.
 * @see {@link util.methodA} for more details
 * 
 * @alias module:util.methodB
 *
 * @param {String} a
 * @return {Boolean}
 */
function methodB(a) {
    return true;
}

/**
 * Always returns false
 * @see {@link util.methodB} for more details
 * 
 * @alias module:util.methodA
 *
 * @param {String} a
 * @return {Boolean}
 */
function methodA(a) {
    return false;
}

Currently generates:

<a name="module_util"></a>
## util

* [util](#module_util)
  * [.methodB(a)](#module_util.methodB) ⇒ <code>Boolean</code>
  * [.methodA(a)](#module_util.methodA) ⇒ <code>Boolean</code>

<a name="module_util.methodB"></a>
### util.methodB(a) ⇒ <code>Boolean</code>
Always returns true.

**Kind**: static method of <code>[util](#module_util)</code>  
**See**: [util.methodA](util.methodA) for more details  

| Param | Type |
| --- | --- |
| a | <code>String</code> | 

<a name="module_util.methodA"></a>
### util.methodA(a) ⇒ <code>Boolean</code>
Always returns false

**Kind**: static method of <code>[util](#module_util)</code>  
**See**: [util.methodB](util.methodB) for more details  

| Param | Type |
| --- | --- |
| a | <code>String</code> | 

Should generate:

<a name="module_util"></a>
## util

* [util](#module_util)
  * [.methodB(a)](#module_util.methodB) ⇒ <code>Boolean</code>
  * [.methodA(a)](#module_util.methodA) ⇒ <code>Boolean</code>

<a name="module_util.methodB"></a>
### util.methodB(a) ⇒ <code>Boolean</code>
Always returns true.

**Kind**: static method of <code>[util](#module_util)</code>  
**See**: [util.methodA](#module_util.methodA) for more details  

| Param | Type |
| --- | --- |
| a | <code>String</code> | 

<a name="module_util.methodA"></a>
### util.methodA(a) ⇒ <code>Boolean</code>
Always returns false

**Kind**: static method of <code>[util](#module_util)</code>  
**See**: [util.methodB](#module_util.methodB) for more details  

| Param | Type |
| --- | --- |
| a | <code>String</code> | 

It seems like there is an issue with linking of methods from extended classes.
Looking at your example, FurQ extends Rapper.
Rapper has two methods .spit() and .battle(). If i click on Rapper.battle(), it links to FurQ.battle() which is not expected. I expect this to take me to the correct Rapper.battle() documentation.

Looking at the source it seems that FurQ @extends Rapper generates <a name="user-content-Rapper+battle"></a> for FurQ.battle(). This will make every extend of Rappers methods link to the first occurrence of <a name="user-content-Rapper+battle"></a> in the document. In this case FurQ.

I would expect FurQ @extends Rapper to output <a name="user-content-FurQ+battle"></a> so it doesn't break linking for every @extends of Rapper.

I have MD style enabled in my jsDoc comments, using `` everywhere.

This library converts them into `, which in turn breaks their content and the layout.

UPDATE: I've just noticed that list indent of the MD syntax - is also not converted correctly, when it is part of @param.

Here's the code documentation, which renders a proper list when converted by jsDoc.

And here's what it looks like, through this module.

although i'm using the grunt plugin to run this, i'm pretty sure the issue is in this library.
Take a look at the file: https://github.com/sagiegurari/angular-web-notification/blob/master/angular-web-notification.js
at the end there is a example tag and due to the fact that the whole js code is indented properly, the doc is also indented and the entire content of the example in the md gets indented too.
that causes the example generated part in the md not to exit from example mode since the ````` tags are indented.

In other words instead of

something here....

It generates to:

             something here....
              ```

These are my notes.

• bugs
  • console.error a warning if a namepath was not found, e.g. if the user entered an incorrect @extends path
  • @param [options.newLine=os.EOL] puts the default in quotes, which it shouldn't
  • --example-lang off not mentioned in usage
  • documenting a quoted property includes the quotes ("\"bg-red\""), it doesn't need them
  • this issue
  • @typedef doesn't show a type, it should be myType : typedef
  • module anchor tag has disappeared, e.g. array-tools#module_array-tools - {{#module}} should always output anchor
  • a custom tag which is a flag (e.g. @non-standard) does not require a colon..
  • should @interface names show in italics, like @abstract
  • @fulfil {{ name: string }[]} - a recordset of room objects doesn't look right.. (see muc)
  • use something if module:something doesn't resolve?
  • do example grouped by kind
  • markdown in param desc looks broke
  • {@link module:fifo~Task} linking to the constructor, not the class
  • set sort order of modules in the main-index and docs
  • jsdoc-parse, if a class is @Private is there any point returning the child members?
  • --include-inherited option, for easier life where there's a class extended from a diff module
  • should sgr.sequence header be ansi.sgr.sequence
  • @properties should appear in the namespace member list
  • jsdoc-parse should throw stuff like 'ERROR: The @memberof tag requires a value.' as an error, not write it to stderr
  • @param [val=1] {number} reports a defaultvalue of "1", string instead of number
  • if @module has no docs, use the description from the exported value (e.g the classdesc)
• tags
  • @order tag to override the computed
  • @requires
  • reflect nullable types
  • extra field ("component" or something) on all members of identifier including the parent for use in sorting
• options / overrides
  • --class-member-index should have table option, showing the description alongside the API (array-tools)
  • 'index-depth' option - set the max depth for main and member index
  • configure symbols (exported, returns etc)
• what to do about "memberof": "<anonymous>".. create an artificial anon identifier to act as the parent?
• document
  • mention @module should always go at the top of the file
  • markdown is rendered in no-gfm param tables, only
  • directly exporting a function should be avoided due to this bug: jsdoc/jsdoc#679
  • leave @default without a value to pickup the correct type
  • @see rule on external without desc
• custom templates
  • possible to have separate index page plus one page per identifier, or hand-picked group of identifiers
• an easier way to export a class than @alias module:cjs/deep? something like @export?
• should dmd be more lenient, not depending on correct hierarchy?
• larger tasks
  • factor markdown-tables out into sep project
  • write dmd input data format spec, to enable other parsers to use dmd
  • internationalisation
  • dmd sandpit
  • refactor dmd partials by structure and content, tags and sections etc..
  • break up into many smaller apps.. using handlebars to build a README is a suggestion, not a dep.. shove multiple commands output into readme, e.g. module-index into {{module-index}}, git shortlog -sn into {{shortlog}}

Currently, nested lists use 2 spaces for indentation:

* [resin](#resin) : <code>object</code>
  * [.models](#resin.models) : <code>object</code>
    * [.application](#resin.models.application) : <code>object</code>
      * [.getAll()](#resin.models.application.getAll) ⇒ <code>Promise.&lt;Array.&lt;Object&gt;&gt;</code>
      * [.get(name)](#resin.models.application.get) ⇒ <code>Promise.&lt;Object&gt;</code>
      * [.has(name)](#resin.models.application.has) ⇒ <code>Promise.&lt;Boolean&gt;</code>
      * [.hasAny()](#resin.models.application.hasAny) ⇒ <code>Promise.&lt;Boolean&gt;</code>
      * [.getById(id)](#resin.models.application.getById) ⇒ <code>Promise.&lt;Object&gt;</code>
      * [.create(name, deviceType)](#resin.models.application.create) ⇒ <code>Promise.&lt;Number&gt;</code>
      * [.remove(name)](#resin.models.application.remove) ⇒ <code>Promise</code>
      * [.restart(name)](#resin.models.application.restart) ⇒ <code>Promise</code>
      * [.getApiKey(name)](#resin.models.application.getApiKey) ⇒ <code>Promise.&lt;String&gt;</code>
      * [.getConfiguration(name, [options])](#resin.models.application.getConfiguration) ⇒ <code>Promise.&lt;Object&gt;</code>
    * [.config](#resin.models.config) : <code>object</code>
      * [.getAll()](#resin.models.config.getAll) ⇒ <code>Promise.&lt;Object&gt;</code>
      * [.getPubNubKeys()](#resin.models.config.getPubNubKeys) ⇒ <code>Promise.&lt;Object&gt;</code>
      * [.getDeviceTypes()](#resin.models.config.getDeviceTypes) ⇒ <code>Promise.&lt;Array.&lt;Object&gt;&gt;</code>

Which causes nested lists to not be displayed correctly:

According to the markdown documentation, nested lists should be implemented with 4 spaces or 1 tab.

Manually editing jsdoc-to-markdown output to use 4 spaces leads to the expected result:

How to replace <code> tag with backticks (```)?

I would like to use jsdoc2md with bitbucket but bitbucket does not render <code> tags.

/** Perform foo
 * @example foo('<a href="#baz">hi!</a>');
 */
function foo(bar)
{
    return '<strong>' + bar + '</strong>';
};

jsdoc test.js gives me:

<pre class="prettyprint"><code>foo('&lt;a href="#baz">hi!&lt;/a>');</code></pre>

jsdoc2md test.js gives me:

<a name="foo"></a>
#foo()
Perform foo

**Example**
foo('<a href="#baz">hi!</a>');

That anchor is interpreted by markdown as html, this should probably be escaped or wrapped within a code block.

I see this code here:

var jsdoc2md = require("jsdoc-to-markdown");
var gutil = require("gulp-util");
var fs = require("fs");

gulp.task("docs", function(done){
    var src = "lib/**/*.js";
    var dest = "api.md";
    var options = {};

    gutil.log("writing documentation to " + dest);
    jsdoc2md.render(src, options)
        .on("error", function(err){
            gutil.log(gutil.colors.red("jsdoc2md failed"), err.message);
        })
        .pipe(fs.createWriteStream(dest));
});

And I am trying to make the given code produce one .md-file per .js-file.. and so far no luck.. basically, I want this behaviour:

gulp.task("docs", function(){

  var src   = 'docstarget/**/*.js';

  return  gulp.src(src)
            .pipe(jsdoc2md.render())
            .on("error", function(err){
              gutil.log(gutil.colors.red("jsdoc2md failed"), err.message);
            })
            .pipe(rename(function(path){
              path.extname = '.md'
            }))
            .pipe(gulp.dest('doxify'));

});

But that code gives me:

jsdoc2md failed Invalid non-string/buffer chunk

How can I achieve what I want? I am using @module-tag, so I cant use the gulp plugin..

I am using this version: "jsdoc-to-markdown": "^0.5.11",, getting same result in "jsdoc-to-markdown": "^0.6.4",

I'm not sure where this belongs, so I'm going to post here. I have this .js file:

/**
 * @function
 * @throws {ReferenceError}
 * @throws {SyntaxError} Syntax error
 * @throws Another error, too.
 */
function foo () { }

The output of jsdoc-parse looks so:

[
  {
    "kind": "function",
    "exceptions": [
      {
        "type": {
          "names": [
            "ReferenceError"
          ]
        }
      },
      {
        "type": {
          "names": [
            "SyntaxError"
          ]
        },
        "description": "Syntax error"
      },
      {
        "description": "Another error, too."
      }
    ],
    "type": {
      "names": [
        "ReferenceError"
      ]
    },
    "description": "Syntax error",
    "name": "foo",
    "longname": "foo",
    "scope": "global",
    "codeName": "foo"
  }
]

This is ok except that "ReferenceError" is repeated outside "exceptions". Then dmd gives this output:

<a name="foo"></a>
#foo()
Syntax error

**Type**: `ReferenceError`  

Here one exception is rendered in place of the function description, one has the caption "Type", and another one is gone.

I'm working on a project that uses grunt-jsdoc-to-markdown to generate the documentation for the function reference, and this is an example of a real file where the problem occurs: https://github.com/fasttime/Q-exact/blob/49f3daf0c2905e828c3544b1c16e6a518dd4c31f/lib/q.js (@throws annotation in constructor).

I am generating separate MD files for each method, using grunt-jsdoc-to-markdown.

What I'd like to change in the output though, is to have the @return + @seesections appear at the bottom, after all the @parameter entries, like in any standard API documentation, and not before it. Is there a way to accomplish this?

In addition, I also would like @summary to appear before @description, and not the other way round as it is done in the default layout.

UPDATE: I have asked the question on StackOverflow.

Currently, adding the @ignore tag to a jsDoc block has no effect. It would be nice if ignore tags did exactly what it says on the tin.

Is it just me or anyone else can't get this working?
I've installed it globally AND locally but still can't make it work (both with and without -g).
Maybe I miss something in your README.md or maybe you forgot to put some requirement on your package.json.
Anyway, great work. Keep at it.

Error: The partial main could not be found
    at new Error (<anonymous>)
    at Error.Exception (/usr/local/lib/node_modules/dmd/node_modules/boil-js/node_modules/handlebars/dist/cjs/handlebars/exception.js:13:41)
    at Object.invokePartial (/usr/local/lib/node_modules/dmd/node_modules/boil-js/node_modules/handlebars/dist/cjs/handlebars/runtime.js:159:11)
    at Object.invokePartialWrapper [as invokePartial] (/usr/local/lib/node_modules/dmd/node_modules/boil-js/node_modules/handlebars/dist/cjs/handlebars/runtime.js:42:39)
    at Object.eval (eval at <anonymous> (/usr/local/lib/node_modules/dmd/node_modules/boil-js/node_modules/handlebars/dist/cjs/handlebars/compiler/javascript-compiler.js:181:23), <anonymous>:3:17)
    at ret (/usr/local/lib/node_modules/dmd/node_modules/boil-js/node_modules/handlebars/dist/cjs/handlebars/runtime.js:106:30)
    at ret (/usr/local/lib/node_modules/dmd/node_modules/boil-js/node_modules/handlebars/dist/cjs/handlebars/compiler/compiler.js:459:21)
    at Object.render (/usr/local/lib/node_modules/dmd/node_modules/boil-js/lib/boil.js:33:29)
    at renderTemplate (/usr/local/lib/node_modules/dmd/node_modules/boil-js/lib/renderStream.js:53:17)
    at RenderStream._flush (/usr/local/lib/node_modules/dmd/node_modules/boil-js/lib/renderStream.js:41:22)

Hi Team,

is it possible to generate the docs from inside the IIFE. Consider this example

var Foo;
(function(){
    /**
     * @summary I am Foo
     */
    Foo = {
        /**
         * @summary Print 'foo' to logs
         */
        log: function () {
            console.log('foo')
        }
    };
}());

jsdoc2md src/foo.js > api.md

jsdoc2md generates an empty file. Only the commenting of the lines 2 and the last one (iife call) makes the docs to be created. Though jsdoc-parse works as expected for both of the variants.

Thanks, Alex

I'm using the module from the command line:
jsdoc2md lib/**/*.js -t readme.hbs > README.md

I'm using glob expression as noted in the documentation and it works ok as long as lib doesn't have subdirectories with files inside.

When adding subdirectory inside lib with files the jsdoc2md ignore the files inside lib and take into account only the files inside lib's subdirectories.

How to take into account all the files inside lib and it's subdirectories ?

Thanks,
Boris

I'm getting this error when I try to run jsdoc2md as a required module in node.js

 /home/.../.bin/docs.js:127
                     jsdoc2md.render('lib/' + name + '.js').on('error', done).
                              ^
TypeError: Object function jsdoc2md(options){
    options = options || {};
    var src = options.src;
    var dmdStream = dmd(options);
    if (src){
        var jsdocStream = jsdocParse(options);

        if (options.json || options.stats){
            return jsdocStream;
        } else {
            jsdocStream.pipe(dmdStream);
            jsdocStream.on("error", dmdStream.emit.bind(dmdStream, "error"));
            return dmdStream;
        }
    } else {
        var jsdocStream = jsdocParse(options);

        if (options.json || options.stats){
            return jsdocStream;
        } else {
            var transform = new Transform();
            jsdocStream.pipe(dmdStream);
            jsdocStream.on("error", dmdStream.emit.bind(dmdStream, "error"));

            transform._transform = function(chunk, enc, done){
                jsdocStream.write(chunk);
                done();
            };
            transform._flush = function(){
                jsdocStream.end();
            };
            dmdStream.on("readable", function(){
                var chunk = this.read();
                transform.push(chunk);
            });
            dmdStream.on("end", function(){
                transform.push(null);
            });
            dmdStream.on("error", function(err){
                transform.emit("error", err);
            });

            return transform;
        }
    }
} has no method 'render'

I have obliterated my node_modules dir, then ran npm install again...

Any Idea why that might be happening?

I am wanting to have multiple files (different modules) generate within a single markdown file. I'm not bothered about the ordering (alphabetical makes sense for this). In order to do this currently I will need to write

{{#module name="foo"~}}
  {{>body~}}
  {{>exported~}}
{{/module}}

{{#module name="bar"~}}
  {{>body~}}
  {{>exported~}}
{{/module}}

I think it would be better to allow for simply

{{>body~}}
{{>exported~}}

Having it when there is no module specified it outputs all of the JSDoc within the body ? or perhaps a set wrapper such as {{#module all}}

Since I'm trying to generate wiki pages out of my jsdocs and the wiki takes care of TOC's, on top of that my wiki doesn't actually allow HTML-tags, it'd be nice if you could allow for an option that skips any TOC generation (including skipping the HTML-anchors for id purposes).

There's no mention of type in in the output for event (output in #9 suggests there once was).

Source:

/**
 * Instance of Test
 *
 * @constructor
 */
function Test () {

}

/**
 * Object event
 *
 * @event Test#event1
 * @type {object}
 * @property {boolean} isPacked - Indicates whether the snowball is tightly packed.
 */

/**
 * String event
 *
 * @event Test#event2
 * @type {string}
 */

Output:

<a name="Test"></a>
## Test
**Kind**: global class  

* [Test](#Test)
  * [new Test()](#new_Test_new)
  * ["event1"](#Test+event_event1)
  * ["event2"](#Test+event_event2)

<a name="new_Test_new"></a>
### new Test()
Instance of Test

<a name="Test+event_event1"></a>
### "event1"
Object event

**Kind**: event emitted by <code>[Test](#Test)</code>  
**Properties**

| Name | Type | Description |
| --- | --- | --- |
| isPacked | <code>boolean</code> | Indicates whether the snowball is tightly packed. |

<a name="Test+event_event2"></a>
### "event2"
String event

**Kind**: event emitted by <code>[Test](#Test)</code>

I would like to render the jsdocs as separate output files, one output file for each input file. This is easily achieved using the Grunt plugin. However, I would also like to generate an index file that links to these.
I got pretty close using the following snippet in a custom .hbs:

{{#identifiers~}}{{#each this~}}
{{#if longname}}- [{{{longname}}}](api/{{{name}}}){{/if}}
{{/each~}}{{/identifiers}}

The problem being that {{{name}}} does not have to match the filename, it accidentally does on most modules, but not on stuff exposed by the modules, for instance. It'd help a lot if the output filename was exposed in a variable available in the handlebars template.

I submit this may actually be a slight abuse of your whole setup and certainly not your primary focus, but it could so easily make this an awesome setup for multi-page wiki's based on markdown!

Running jsdoc2md againt a bunch of js files and getting weird error.

C:\Work\>jsdoc2md C:\Work\src\lib\*.js > 1.md
Parameter 'url' must be a string, not undefined

Something is wrong but what and where?

Hey congrats for the upcoming version, I gave it a try and I like it a lot. Great improvements.

I found one little issue when escaping pipes in tables, for example when a value can be {String | Number}. In NPM the markdown doesn't seem to scape the . You can see an example in my published package: https://www.npmjs.com/package/tokenbucket

After having a quick look it seems that the HTML character (|) should be used instead.

Please support TypeScript style class code.

http://goo.gl/JMi7Wu
TypeScript convert class syntax to prototype style code, but it emit immediate function pattern.
but I can't found ignore immediate function in jsdoc-to-markdown.

I want do this image.

$ jsdoc2md lib/**/*.js -j | \
  sed -e 's/<anonymous>~//' | \
  sed -e 's/"memberof": "<anonymous>",//' | \
  sed -e 's/"scope": "inner"/"scope": "global"/' | \
  dmd --template README.tmpl.md > README.md

but dmd not support --template option.

Hi,
I am using the method posted here for splitting a class prototype in multiple files (submodules).
The problem is that prototype functions are marked as static this way, because looking at the submodule files only that's what you understand. But it's wrong, because they're all prototype functions.

Is there something that can be done to avoid this?

Thank you!

Is splitting a single monolithic file with jsdoc-style comments in separate files supported? If a single file exposes multiple classes is there a way to generate separate files for each definition? Perhaps using some other meta-information or using a parameter which takes into account the type definitions?

Some of the anchors generated by jsdoc2md contain the character "#" (e.g. `<a name="Primer#publish"></a>'). I don't think that's a legal character in an HTML anchor, and it does cause problems with some markdown renderers (e.g. Stash) which just omit the anchor link entirely.

See: http://stackoverflow.com/questions/2849756/list-of-valid-characters-for-the-fragment-identifier-in-an-url

I'm looking into automatically generating README.md from html elements that contain jsdoc within inline javascript blocks as well within html comment blocks. Would something like this be possible with jsdoc-to-markdown?

Hi, I just updated to the latest grunt-jsdoc-to-markdown and noticed that the current output of my files is no longer being rendered correctly by Sublime (preview in browser) and also in Atom.io (preview-plugin).

It seems to be something related to the additional tabs/spaces in the beginning of the line. If you need for info on how to reproduce let me know.

Cheers

It would be nice if instead of a boolean on/off switch for "separators" you could specify the nature of the separator. In Stash, for example, the single dash on a line by itself just renders as a single dash on a line by itself, not as a horizontal-rule. So, something like:

jsdoc2md --separators "<hr />"
jsdoc2md --separators "----"

...would be helpful.

Using the following template in a .hbs file, jsdoc-to-markdown does not produce a listing with one member for the index of modules containing one single member:

# Index

{{#modules~}}
  ## {{name}}
  > {{>body}}
  {{>member-index~}}
{{/modules}}

# Modules and methods

{{#modules~}}
  ##   {{name}}
  > {{>body~}}
  {{>members~}}
{{/modules}}

Am I missing something or is this indeed a bug?

How can I output a single function (the whole documentation, not just the name) of a certain module in a hbs template file? This is not very clear in the selector helpers documentation.

Looking at this file:
https://github.com/IjzerenHein/famous-listview/blob/master/docs/ListView.md

When clicking the link 'new ListView(options)', it jumps to the top of the document rather than to the constructor.

Cheers

thread for tracking relevant issues in jsdoc

The example tag allows captions but when I attempt to use captions, jsdoc2md throws the caption tags and their contents into the example code. Here is an example:

/**
 * My cool API.
 *
 * @example <caption>Suggested Usage</caption>
 * console.log(myObj.myCoolApi());
 */
function myCoolApi () { }

Right now, the generated example (without header) looks like this:

<caption>Suggested Usage</caption>
console.log(myObj.myCoolApi());

When I'd expect the generated example to look like this:

console.log(myObj.myCoolApi());

I would also like to see the example header use the caption when available. So based on the example above, I'd like to see **Example _(Suggested Usage)_** for the generated example header instead of **Example**. Of course, how you style/display the caption in the end doesn't matter to me as long as it's used in some way so people viewing my examples can also view the caption since it is usually important.

If you're cool with this, I'll do the work and submit a PR. I just didn't want to go through the effort only to be told you didn't want it.