example.js

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(" ");
};

meta-doc.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
};

meta-docs.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