metadocs

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> 

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

sandbox.js.patch

From eb1ef52583c673abc10aed8856bbc2d754acca69 Mon Sep 17 00:00:00 2001
From: Irakli Gozalishvili <rfobic@gmail.com>
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

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
};