tj / dox Goto Github PK

If you add "module visionmedia dox" to nDistro and run it, you'll end up with:

$ pwd
lib/node
$ index.js -> ../../modules/dox/lib/index.js

Running "$ ./bin/dox" will give you a module not found error. To correct this, you have to manually move "index.js -> dox.js". I assume the correct fix would be to modify the dox repo such that "visionmedia/dox/lib/index.js" is symlinked to "visionmedia/dox/lib/dox.js".

If you'd like me to fork & correct this, let me know :) I think I've forked enough of your work for the day :P

Have a good night!

In the following code
Spo.prototype.car = {};
Is parsed to have the ctx string
Spo.prototypcar

Which later down the line I believe is causing the failure of Spo.prototype.car.dance to parse properly

/*

• The spo object
  */

var Spo = {};

/*

• get on the bus
  */

Spo.prototype.car = {};

/**
*The dance party function.

*example:

•  dance('spo');
  

•  will give you the out put
  
• @param {String} Spo what will you do ?
  */

Spo.prototype.car.dance = function(spo){
console.log(spo);
};

I will check it out more but I don`t think I am smart enough yet to fix your code Xp

just leave the markdown

I see this pull request so I think it's a feature not a bug :p

But when I parse this comment:

/**
 * Parse the given comment `str`.
 *
 * The comment object returned contains the following:
 * ...
 */

Then description.body is <h2>The comment object returned contains the following</h2>\n\n<p>...</p>
And without the colon after following it's <p>The comment object returned contains the following<br />...</p>

I think it would be better if it always stays with <p> and if you need <h2> then you can write:

/**
 * Parse the given comment `str`.
 *
 * ## The comment object returned contains the following:
 * ...
 */

This will always returns <h2>The comment object returned contains the following</h2>\n\n<p>...</p> with or without colons.

Otherwise if it should stay as it currently is, then there is a small bug because this comment

/**
 * Parse the given comment `str`.
 *
 *  The comment object returned contains the following
 * ...
 */

will be parsed in <p>The comment object returned contains the following:<br />...</p> even with colon (Notice the two spaces before The comment object...).

It is not possbible to recursively process a folder of files, or is it? What am I missing here? Hardly any documentation to be found on the conf.json file either...what gives?

According to the dox.parseTypes function, there seems to be no support for parsing types for @throws declarations. Is there any particular reason for this?

encoding gets fucked up or something

between files / functions

I would like, that you to add support of JSDoc meta tags like /#nocode+*/ /#nocode-*/

• just ignore them in doc block of dox.
  I think support of groupping is not important, but u can also it
  /**#@+
  @Private
  @memberof Foo
  */

  function baz() {}
  function zop() {}
  function pez() {}

  /*#@-/
  http://code.google.com/p/jsdoc-toolkit/wiki/MetaTags

@event -> * even: t
@function -> * functio: n

To test all u can run dox against jsdoc-toolkit/app/test/*.js

/usr/local/lib/node_modules/dox/lib/dox.js:70
comment.code = code;
^
TypeError: Cannot set property 'code' of undefined
at Object.parseComments (/usr/local/lib/node_modules/dox/lib/dox.js:70:18)
at [object Object]. (/usr/local/lib/node_modules/dox/bin/dox:40:17)
at [object Object].emit (events.js:61:17)
at afterRead (fs.js:878:12)
at wrapper (fs.js:245:17)

For every file I try to process.

36 files in connect

to --api

Hi!

Is it possible to use dox with Windows PowerShell?

The problem is that PowerShell does not implement < operator. Example:

C:\work\myproject\> dox < app.js
The '<' operator is reserved for future use.
At line:1 char:6
+ dox < <<<<  app.js
    + CategoryInfo          : ParserError: (<:OperatorToken) [], ParentContainsErrorRecordException
    + FullyQualifiedErrorId : RedirectionNotSupported

Any ideas?

As a workaround, I am currently using command-prompt to run dox and - for everything else - PowerShell.

This is more common type of JSDoc documentation
/**
* @constructor Button
*
* @param {Object} context
*
* @Augments CommonObject
/
This type is less common:
/*
@constructor Button

 @param {Object} context

 @augments CommonObject
 */

Ur parser converts leading asterisk to html ol list.

If you have a file like this:

var sys = require('sys');

/** some docs */
function foo() {};

The require and function end up on the left formatted as text, and the comment ends up on the right formatted as code.

not indented form

Could you share a generic Jade template to display JSON data with?

fucks up on Connect

http://www.senchalabs.org/connect/directory.html

/**
 * Parse tag type string "{Array|Object}" etc.
 *
 * @name is arbitrary
 * @param {String} str
 * @return {Array}
 * @api public
 */
exports.test = function() {
  return "*/*";
};

the / broke parse

css? or js? have a flag

Is there a link to a complete documentation for how to document code compatible with dox?

I miss specially how to document functions that takes a variable number of arguments, and arguments that accept any types. I saw JSDoc uses {...Type} for the former and {*} for the latter, maybe it's something like {...*} for an argument with variable number of arguments of all types.

How would you document a function that takes a string as the first argument, and a callback as the last, and any number of arguments of any type in between?

/**
 * Description.
 *
 * @param {String} key
 * @param {...*} argument
 * @param {Function} callback
 * @api private
 */

Also, how to document an argument that can be of e.g. Object or String types and be omitted or set to null? In JSDoc I see something like {?Object|String} or @param {Object|String} [arg].

Thanks in advance.

https://github.com/chjj/marked

he exposes the parser so we can leverage this to expose granular data, great for more opinionated HTML output

dox is broken on lates version of npm node due to module loader changes.

directives for jshint should be ignored:

  /*jshint latedef:false */
  var define = require('amdefine')(module);

results in

{
    "tags": [],
    "description": {
      "full": "<p>shint latedef:false</p>",
      "summary": "<p>shint latedef:false</p>",
      "body": ""
    },
    "ignore": false,
    "code": "var define = require('amdefine')(module);\n}\n\n\ndefine(function (require) {\n\t'use strict';\n\tvar _ = require('underscore');\n\t\n\tvar type = function(typename,
 required, options) {\n\t\t\tvar t = {type: typename};\n\t\t\tif (required) {\n\t\t\t\tt.required = true;\n\t\t\t}\n\t\t\treturn _.extend(t, options);\n\t};\n\t\n\tvar combine = 
function(",
    "ctx": {
      "type": "declaration",
      "name": "define",
      "value": "require('amdefine')(module)",
      "string": "define"
    }
  }

Those directives should really be treated as regular code. JSHint does not allow a space between the comment start and jshint or global:

ok: /*jshint latedef:false */, /*global console:true */
not recognized by jshint: /* jshint onevar:false */

For fun and education, I'm working on a port to CoffeeScript that reads .coffee files instead of .js files.

https://github.com/cpsubrian/coffee-dox

When working on it I could not get the first tests (the ones using the 'a.js' fixture) to pass.

Markdown is not converting <> to entities in "". It looks like Dox is suffering from the same bug.

Is this is regression in github-flavored-markdown?

"foo" should not be "foo" etc

or add an option, annoying myself

Suppose I have the following JS file:

/** Wrap everything in a function for some reason */
(function() {
  var state = 0;

  /** Increment state by 1 */
  function inc() {
    state++;
    return state;
  };

  /** Publically expose `inc` */
  return inc;
})();

The documentation generated for inc is improperly indented. The first line isn't indented at all, but the rest is indented at the same level as the file, so it ends up looking like this:

function inc() {
    state++;
    return state;
  };

It would be preferable to either not remove the indentation on the first line, or to re-indent the entire thing.

See the discussion on this StackOverflow posting:
http://stackoverflow.com/questions/6096649/documenting-node-js-projects/6995688#6995688

Basically, mere mortals are intimidated by the task of creating a template to turn pure "unopinionated" JSON code structure metadata into human consumable "opinionated" HTML. The concept of factoring apart the parser from the formatter is great; we just need an example of how a template would work.... a starting point. Adding this (plus a mention in the README.md) would go a long way towards making this module consumable by others.

As much as I'd love to do the work myself and submit a "pull request", honestly, I'm not entirely sure how to create such a template either. Not that I'd ever admit that... ;)

Cheers,
--- Dave

exports.parseCodeContext dont support tab. see here https://github.com/visionmedia/dox/blob/master/lib/dox.js#L239

bug: In all the regexp, all white char MUST be space and can not be tab. for example at https://github.com/visionmedia/dox/blob/master/lib/dox.js#L239

  // function statement
  if (/^function (\w+) *\(/.exec(str)) {

so codes with tab and no space wont be parsed.

possible solution: add tab as a possibility in all regexp

in dox / lib / dox / markdown / test / fixtures / PHP_Markdown-from-MDTest1.1.mdtest directory, these file names are causing some issues with a tool that we don't really have control of. Is it possible to replace these parenthesis?

    Inline_HTML_(Simple).html   
Inline_HTML_(Simple).json
Inline_HTML_(Simple).text
Inline_HTML_(Span).json
Inline_HTML_(Span).text
Inline_HTML_(Span).xhtml

I have a 'working' coffee-script version over here: https://github.com/cpsubrian/coffee-dox. All tests are passing.

I still need to add support for some coffeescript specific stuff (like classes).

If there is demand (and it has a chance of merging) I'd be happy to work up ideas for a language agnostic version of Dox. Could create the js parser and coffeescript parser.

I have not been following this issue queue so I'm not sure what other improvements and bug fixes are not in master yet.

The Makefile rule for docs specifies --verbose, --out, --title, --github, --index command-line options. None of these seem to be implemented any more. Maybe that's why npm install dox followed by make docs in node_modules/dox just hangs.

I guess this is leftover from the "no longer generates an opinionated structure or style for your docs" change. Alas the web still links and describes the "dox" that no longer exists, e.g. http://dailyjs.com/2011/01/20/framework-part-47/