tj / dox Goto Github PK
View Code? Open in Web Editor NEWJavaScript documentation generator for node using markdown and jsdoc
JavaScript documentation generator for node using markdown and jsdoc
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
/*
var Spo = {};
/*
Spo.prototype.car = {};
*example:
dance('spo');
will give you the out put
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
dox -h
Usage: dox [options]
Options:
-h, --help output usage information
-V, --version output the version number
-d, --debug output parsed comments for debugging
Examples:
# stdin
$ dox > myfile.json
# operates over stdio
$ dox < myfile.js > myfile.json
node.js:201
throw e; // process.nextTick error, or 'error' event on first tick
^
Error: process.stdout cannot be closed.
at WriteStream.<anonymous> (node.js:284:20)
at Command.<anonymous> (/usr/local/lib/node_modules/dox/node_modules/commander/lib/commander.js:908:18)
at Command.emit (events.js:88:20)
at Command.parseOptions (/usr/local/lib/node_modules/dox/node_modules/commander/lib/commander.js:439:14)
at Command.parse (/usr/local/lib/node_modules/dox/node_modules/commander/lib/commander.js:323:20)
at Object.<anonymous> (/usr/local/lib/node_modules/dox/bin/dox:32:9)
at Module._compile (module.js:444:26)
at Object..js (module.js:462:10)
at Module.load (module.js:351:31)
at Function._load (module.js:310:12)
node v0.6.9
dox v0.1.3
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
/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/
A declarative, efficient, and flexible JavaScript library for building user interfaces.
๐ Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. ๐๐๐
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google โค๏ธ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.