Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Loading…

Support for undocumented files #29

Closed
wants to merge 3 commits into from

2 participants

@cachafla

Hey,

So basically my commit was about supporting undocumented files to be correctly parsed. I started documenting a project with your library but found that when there are no proper docstrings the file gets parsed incorrectly. I basically added a conditional to check when the regex split array was of size 1. In which case there were no docstrings found and there is no documentation yet for the source code.

If you want to see how it works try adding some undocumented javascript code before and after applying this patch.

Thanks!

cachafla added some commits
@cachafla cachafla Support undocumented files. When a file had no documentation at all t…
…he source code was being sent to the left. When parts.length is 1, the only match in the regex is the code itself, a single block gets pushed into the array.
7467809
@cachafla cachafla Suport ignoring shebangs d46a32a
@cachafla cachafla Better detection of comments vs blocks. Allow source code not beginni…
…ng with comments to be properly documented.
4924f15
@evindor
Collaborator

Outdated.

@evindor evindor closed this
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Commits on Feb 24, 2011
  1. @cachafla

    Support undocumented files. When a file had no documentation at all t…

    cachafla authored
    …he source code was being sent to the left. When parts.length is 1, the only match in the regex is the code itself, a single block gets pushed into the array.
  2. @cachafla

    Suport ignoring shebangs

    cachafla authored
  3. @cachafla

    Better detection of comments vs blocks. Allow source code not beginni…

    cachafla authored
    …ng with comments to be properly documented.
This page is out of date. Refresh to see the latest.
Showing with 62 additions and 36 deletions.
  1. +62 −36 lib/dox/index.js
View
98 lib/dox/index.js
@@ -41,7 +41,7 @@ var title = 'Dont forget to use --title to specify me!';
/**
* Parse JSDoc.
- *
+ *
* @type Boolean
*/
@@ -49,7 +49,7 @@ var jsdoc = true;
/**
* Project description.
- *
+ *
* @type String
*/
@@ -57,7 +57,7 @@ var desc = '';
/**
* Intro text file name.
- *
+ *
* @type String
*/
@@ -65,7 +65,7 @@ var intro = '';
/**
* Show private code.
- *
+ *
* @type Boolean
*/
@@ -73,7 +73,7 @@ var showPrivate = false;
/**
* Github url for the ribbon.
- *
+ *
* @type String
*/
@@ -118,7 +118,7 @@ function log(msg){
exports.parse = function(args){
var files = [];
-
+
// Require an argument
function requireArg(){
if (args.length) {
@@ -174,23 +174,23 @@ exports.parse = function(args){
files.push(arg);
}
}
-
+
if (files.length) {
log('parsing ' + files.length + ' file(s)');
var pending = files.length;
-
+
// Style
log('loading ' + style + ' style');
var head = fs.readFileSync(__dirname + '/styles/' + style + '/head.html', 'utf8');
var foot = fs.readFileSync(__dirname + '/styles/' + style + '/foot.html', 'utf8');
var css = fs.readFileSync(__dirname + '/styles/' + style + '/style.css', 'utf8');
-
+
if (intro)
desc = (desc || '') + fs.readFileSync(intro, 'utf8');
-
+
// Substitutions
head = head.replace(/\{\{title\}\}/g, title).replace(/\{\{style\}\}/, css);
-
+
// Ribbon
if (ribbon) {
log('generating ribbon');
@@ -199,10 +199,10 @@ exports.parse = function(args){
+ ' src="http://s3.amazonaws.com/github/ribbons/forkme_right_darkblue_121621.png">'
+ '</a>');
}
-
+
sys.print(head);
sys.print('<table id="source"><tbody>');
-
+
// Render files
var first = true;
files.forEach(function(file){
@@ -214,14 +214,14 @@ exports.parse = function(args){
sys.print('<tr><td><h1>' + title + '</h1>' + desc + '</td><td></td></tr>');
first = false;
}
- sys.print('<tr class="filename"><td><h2 id="' + file + '"><a href="#">'
- + path.basename(file, '.js') + '</a></h2></td><td>'
+ sys.print('<tr class="filename"><td><h2 id="' + file + '"><a href="#">'
+ + path.basename(file, '.js') + '</a></h2></td><td>'
+ file + '</td></tr>');
sys.print(render(str, file));
--pending || sys.print(foot, '</tbody></table>');
});
});
-
+
} else {
throw new Error('files required.');
}
@@ -244,26 +244,52 @@ var render = exports.render = function(str, file){
var parts = str.split(/\s*\/\*([^]+?)\*\/\s*/g),
blocks = [];
- // Populate blocks
- for (var i = 0, len = parts.length; i < len; ++i) {
- var part = parts[i],
- next = parts[i + 1] || '';
- // Empty
- if (/^\s*$/.test(part)) {
- continue;
- // Ignored comment
- } else if (/^!\s*\*/.test(part)) {
- continue;
- } else {
- ++i;
-
- // Support @ignore and --private
- if (utils.ignore(part) || (utils.isPrivate(part) && !showPrivate)) continue;
- var part = part.replace(/^ *\* ?/gm, '');
- blocks.push({
- comment: markdown.toHTML(utils.toMarkdown(part)),
- code: koala.render(".js", utils.escape(next))
- });
+ // Populate blocks, when there is only one part then no docstrings were
+ // found and a single 'code' block should be shown to the right
+ if (parts.length == 1) {
+ blocks.push({
+ comment: markdown.toHTML("Undocumented"),
+ code: koala.render(".js", utils.escape(parts[0]))
+ });
+ } else {
+ for (var i = 0, len = parts.length; i < len; ++i) {
+ var part = parts[i];
+
+ // Empty
+ if (/^\s*$/.test(part)) {
+ continue;
+ // Ignored comment
+ } else if (/^!\s*\*/.test(part)) {
+ continue;
+ } else {
+
+ // Support @ignore and --private
+ if (utils.ignore(part) || (utils.isPrivate(part) && !showPrivate)) {
+ ++i;
+ continue;
+
+ // String looks like a comment. In this case next should be a
+ // code block
+ } else if (/^ *\* ?/gm.test(part)) {
+ ++i;
+ var part = part.replace(/^ *\* ?/gm, '');
+ comment = markdown.toHTML(utils.toMarkdown(part));
+ next = parts[i] || '';
+
+ // String is a code block. In this case there is no comment for
+ // it and it should go to the right. This is the case for files
+ // do not necessarily begin with comments or files that begin
+ // with a shebang
+ } else {
+ comment = "";
+ next = part;
+ }
+
+ blocks.push({
+ comment: comment,
+ code: koala.render(".js", utils.escape(next))
+ });
+ }
}
}
Something went wrong with that request. Please try again.