Skip to content

Instantly share code, notes, and snippets.

@Gozala

Gozala/README.md

Forked from Gozala/meta-docs.patch
Created October 27, 2009 20:30
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save Gozala/219927 to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save Gozala/219927 to your computer and use it in GitHub Desktop.
Download ZIP
metadocs
Raw
README.md

Idea of documenting js code inspired by python and EcmaScript 5 "strict mode"; Works on narwhal, firefox, chromium, safari (not tested on ie)

Below is the example of usage in this in the the shell

gozala@ijarti:~/Projects/meta-doc  (master)$ narwhal
Rhino 1.7 release 3 PRERELEASE 2009 04 05
js> require("meta-doc/toolkit").doc()
toolkit module
provides utilities for getting a live docs
@type module
js> typeof require("/Users/gozala/Projects/meta-doc/examples/functions.js").example
function
js> require("/Users/gozala/Projects/meta-doc/examples/functions.js").example.doc()
This is a function foo which is supposed to do something.
But the best thing is that it has nice documentation in it.
@param {String} a                   first argument
@param {String} b                   second argument
@returns {String}                   Concatinated string literal
js> require.doc()
Not documented
js>
Raw
example.js
// example of function using metadocs
exports.example = function(a, b) {
['This is a function foo which is supposed to do something.\n\
But the best thing is that it has nice documentation in it.\
@param {String} a first argument\
@param {String} b second argument\
@returns {String} Concatinated string literal']
return [a, b].join(" ");
};
Raw
sandbox.js.patch
From eb1ef52583c673abc10aed8856bbc2d754acca69 Mon Sep 17 00:00:00 2001
From: Irakli Gozalishvili <[email protected]>
Date: Tue, 27 Oct 2009 21:29:36 +0100
Subject: [PATCH] meta docs
---
lib/sandbox.js | 3 +++
1 files changed, 3 insertions(+), 0 deletions(-)
diff --git a/lib/sandbox.js b/lib/sandbox.js
index eb67a4c..1b8e1f5 100644
--- a/lib/sandbox.js
+++ b/lib/sandbox.js
@@ -248,6 +248,9 @@ exports.Sandbox = function (options) {
'path': factory.path
};
factory(require, exports, module, subsystem, subprint);
+ if (factory.doc) exports.doc = module.doc = function doc() {
+ return factory.doc();
+ }
if (sandbox.debug) {
// check for new globals
--
1.6.1.3+GitX
Raw
toolkit.js
['toolkit module\n\
provides utilities for getting a live docs\n\
@type module']
var EXTRACTOR = new RegExp( // (function functionName(foo, bar) {....
"^" +
"\\s*" +
"\\({0,1}" + // "("
"\\s*" +
"function" + // "function"
"\\s*" +
"([^\\(\\s]*)" + // "functionName" - $1 - if not anonymus
"\\s*" +
"\\(" + // "("
"([^\\)]*)" + // "foo, bar" - $2 - arguments
"\\s*" +
"\\)" + // ")"
"\\s*" +
"\\{" + // "{"
"\\s*" +
"\\/*" + // "/" - optional can be comment block
"\\**" + // "*" - optional can be multiline comment
"\\s*" +
"\\[{0,1}" + // "[" - optional to make it work in firefox comment should be in array
"\\s*" +
"(\"|')" + // " or ' - $3 - metadoc string opening quote
"([\\s\\S]*)" + // ... - $4 - rest of the source till the last close quote
"(\"|')"
,
"m");
Function.prototype.doc = function doc() {
var $ = (this.toSource || this.toString).call(this).match(EXTRACTOR);
if (!$ || !$[4]) return "Not documented";
var extracts = $[4].split($[3]);
var slice;
var doc = [slice = extracts.shift()];
while ((slice = extracts.shift()) && slice.charAt(slice.length -1) == "\\")
doc.push(slice);
return doc.join("").replace(/\\n|\\\n/g, "\n") // put line brakes instread of "\n" and "\" chars followed by linebrake
.replace(/\@/g, "\n@") // splitting seperating attributes by line breaks
.replace(/\n\s+|\s+\n/g, "\n") // trimming lines
};
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment