jdalton/docdown

A simple JSDoc to Markdown generator.

docdown v0.7.3

A simple JSDoc to Markdown documentation generator.

Usage

var docdown = require('docdown');

var markdown = docdown({
  'path': filepath,
  'url': 'https://github.com/username/project/blob/master/my.js'
});

docdown's Issues

Handle Namespaces

Having issues generating with namespaces for "classes"
https://gist.github.com/mattpodwysocki/5118923

Generates the following output:
https://github.com/mattpodwysocki/docdown.js/wiki/FooBar#wiki-compositedisposableprototypeadd

Version number is not up to date

The version number of the package is not up to date. On npm, it's at v0.4.0, while it's still 0.3 in the readme (I'd suggest simply removing the version number from the title) and more surprisingly in the package.json. Was it published on npm from a local machine without the repo being updated?

Port Docdown to JS from PHP [$115 awarded]

Lo-Dash v3.0.0 requires that Docdown be converted from PHP to JS (npm package) for easier use when generating inlined documentation for individual method packages. There's currently a WIP JS branch that is not in a workable state but could be with a little elbow grease.

While we can still publish Lo-Dash v3.0.0-pre, this is blocking the full v3.0.0 release.

Support ES6/2015 class syntax

Version 0.5.1 doesn't appear to support class syntax yet. I've just converted a library of mine and discovered the issue.

Running the latest version on the following example produces a pretty much empty markdown file.

export default class Test {
    /**
     * Test
     *
     * @param {string} msg Something to say
     * @return {boolean} Test boolean.
     */
    say(msg) {
        return false;
    }
}

Generated markdown:

# 

<!-- div class="toc-container" -->

<!-- /div -->

<!-- div class="doc-container" -->

<!-- /div -->

 [1]: # "Jump back to the TOC."

Source link error/incompatibility with GitHub

Using docdown 0.7.2, generated links to sections of the source code don't render as links when preceded by an html element (in github, at least).

For example, docdown generates the following markup for a function of mine:

<h3 id="available"><a href="#available">#</a>&nbsp;<code>available(full)</code></h3>
[&#x24C8;](https://github.com/helion3/inspire-tree/blob/master/src/tree.js#L243 "View in source") [&#x24C9;][1]

However, it renders as:

# available(full)

[Ⓢ](https://github.com/helion3/inspire-tree/blob/master/src/tree.js#L243 "View in source") [Ⓣ][1]

When I separate the elements with a new line, or when I remove the h3, the link renders:

Ⓢ [Ⓣ][1]

Here's the script I use which runs docdown and writes the resulting files: https://github.com/helion3/inspire-tree/blob/master/scripts/docs.js

You can see an example affected markdown file here: https://github.com/helion3/inspire-tree/blob/master/docs/tree.md

Issues with CR-LF line endings

Running docdown from bash for Windows (https://msdn.microsoft.com/commandline/wsl/about) resulted in extra new lines inserted into the documentation. What is only a single new line in the jsdoc comment and therefore should be ignored by docdown is treated as a double newline and so <br>'s are inserted into the markdown.

<h3 id="itblmapiterable-iteratee_identity"><code>itbl.map(iterable, [iteratee=_.identity])</code></h3>
[&#x24C8;](https://github.com/harrysarson/itbl/blob/2.0.0/itbl.js#L569 "View in source") [&#x24C9;][1]

Creates a new iterable whose iterators will have values corresponding to the value
<br>
<br>
of the Iterator of the original iterable run through `iteratee`.
<br>
<br>
The iteratee is invoked with only one argument *(value)*.

#### Since
0.1.0
#### Arguments
1. `iterable` *(Iterable)*: Iterable to map values of.
2. `[iteratee=_.identity]` *(Function)*: Function to run each value though.

#### Returns
*(itbl)*: A new mapped iterable

Whilst this is quite a niche problem, any one using files created on windows and not properly converted would have the same problem.

param parse bug

/**
 * a bug about object param 
 * @param {object} args args is a object
 * @param {dom} args.target but can't parse the target in args
 * @type function
 */
var _autoInit = function (args) {
    var dom = args.target,

i can't got args.target in result....

PHP 5.5 compatibility

PHP 5.5 supports generators now, and therefore introduced an internal global class named Generator.

The custom Generator class in docdown should be renamed to something else, to avoid these errors:

PHP Fatal error:  Cannot redeclare class Generator in /foo/bar/docdown/src/DocDown/Generator.php on line 8

Fatal error: Cannot redeclare class Generator in /foo/bar/docdown/src/DocDown/Generator.php on line 8

error on empty tocgroup push

as per docs

https://github.com/jdalton/docdown#usage

var markdown = docdown({
  path: '/Users/james/code/__priority/_chains/chain-able/src/Chainable.js',
  url: 'https://github.com/fluents/chain-able/blob/master/src/Chainable.js',
})

wrapping this line in try catch makes it generate the md https://github.com/jdalton/docdown/blob/master/lib/generator.js#L147

Use doctrine to parse jsdoc

See doctrine.

Constructor entries break the parser

Attempting conversion on a source file that contains a class constructor or function marked w/ @constructor breaks the parser.

Cause

The issue starts here

docdown/lib/generator.js

Line 100 in 297e61f

organized = {},

Further down it attempts to dynamically assign the key organized.constructor

docdown/lib/generator.js

Line 130 in 297e61f

tocGroup = organized[category] || (organized[category] = []);

This results in a tocGroup receiving a TypeError as a value which throws when tocGroup.push is called here

docdown/lib/generator.js

Line 147 in 297e61f

tocGroup.push(entry);

Resolution

The issue is due to trying to use an object that inherits from Object as a key/value store. The name of organized (ie an array) tries and fails to overwrite the existing constructor function.

To fix this, organized can be initialized with an object literal that doesn't inherit any properties/methods from Object with.

 organized = Object.create(null),

It's possible this may also resolve #45

multiple API variants

How would you go about defining multiple API variants that are so dissimilar to each other that defining them inside one JSDoc @param's list would be very confusing? Does docdown support this?

E.g., take this method:

Possible API variants:
1: #on( {string}, {string}, {Function} );
2: #on( {string}, {Function} );
3: #on( {Object}, {string} );

Putting it inside one JSDOC would result in something like this:

@param {string|Object} [a] if string, optional... if Object, not optional.
@param {string|Function} b if 1st arg object, this should be... Else this should be ...
@param {Function} [c] if previous 2args supplied, this should be handler...

Which we'd be better off not using @param at all, and simply writing it out in an @example or notes.

Thoughts?

about docdown, i wrote a gulp plugin for it :)

I love docdown!
And I wrote a gulp plugin for you, I hope you love it too :)

https://www.npmjs.com/package/gulp-docdown

Object function toString() has no method 'push' in generator.js

After shrinkwrapping to lodash/lodash@faddd94 to get past #20, using the example script

var docdown = require('docdown');

var filepath = '/path/to/project/lib/QueryBuilder.sjs';

// generate Markdown
var markdown = docdown({
  'path': filepath,
  'url': 'https://github.com/username/project/blob/master/my.js'
});

I'm getting the following error:

/path/to/project/node_modules/docdown/lib/generator.js:177
        tocGroup.push(entry);
                 ^
TypeError: Object function toString() { [native code] } has no method 'push'
    at /path/to/project/node_modules/docdown/lib/generator.js:177:18
    at arrayEach (/path/to/project/node_modules/docdown/node_modules/lodash/dist/lodash.js:295:11)
    at Function.forEach (/path/to/project/node_modules/docdown/node_modules/lodash/dist/lodash.js:5301:11)
    at generateDoc (/path/to/project/node_modules/docdown/lib/generator.js:141:5)
    at docdown (/path/to/project/sojourns/node_modules/docdown/index.js:30:10)
    at Object.<anonymous> (/path/to/project/sojourns/docs.js:6:16)
    at Module._compile (module.js:456:26)
    at Object.Module._extensions..js (module.js:474:10)
    at Module.load (module.js:356:32)
    at Function.Module._load (module.js:312:12)

I know both this and lodash are using pre-release versions here, but I'd like to help them get them working together. Any help would be much appreciated.

OS X 10.9.5
Node 0.10.31
npm 1.4.23

Keep the order of methods as in source

Would be great if there is a sorting option, which keeps the order as it is in source.

Prep for npm publish.

In prepping for publishing to npm I'll be lowering the version to 0.1.0 since this hasn't really been hammered on in JS land yet.

TOC: Properties starting with "$" lead to duplicated link label

Source:

this.$items = $('…');
this.bla = 'bla';

Output:

## `Properties`
* [`$items$items`](#$items)
* [`bla`](#bla)

New tag to categorize the methods in TOC

Most of the JavaScript libraries use single namespace where put all of the utility methods. Lodash is an example for that, Underscore etc.
For documentation would be great if there is an easy way to categorize the methods. For example if there is a JSDoc tag for that:

 @category Array
_.map = function (){};

 @category Function 
_.bind = function (){}; 

Add support for the @since tag.

Related to lodash/lodash#993.

Linking separate file with examples

What I ever wanted is instead of put the examples of the usage directly in source code, to have separate file with examples, which will be used for generated examples in the documentation.
We will have double bonus from that. Clean source code, and good examples in the documentation.

Issue with multi-line function descriptions

    /**
     * Foo bar baz let's say this line is very long and reaches the 80-char limit
     * but the sentence continues on the next line, or maybe it's even longer
     * and makes it all the way to the third line.
     * @memberOf foo
     * @param {String} input lorem ipsum.
     * @returns {String} lorem ipsum.
     */
    function x(y) {}

Generates the following Markdown:

Foo bar baz let's say this line is very long and reaches the 80-char limit
     * but the sentence continues on the next line, or maybe it's even longer
     * and makes it all the way to the third line.

In other words, the tab + space + * character isn’t trimmed from the second (and third, fourth, etc.) line. This is an issue when generating docs for Punycode.js.

Lodash dependency version in JavaScript port

I'm getting an error, Object function lodash(value) {…has no method 'escapeRegExp'. It looks like escapeRegExp was introduced in 3.0.0, but the package.json dependency is declared as ^2.4.1.