From 1abe982e2ff863eed4eaa7a69b8d241504cc9fdb Mon Sep 17 00:00:00 2001
From: Michael Mathews <micmath@gmail.com>
Date: Fri, 21 Oct 2011 00:01:34 +0100
Subject: [PATCH] Added feature: @lends doc comments can now appear before the
 return statement, when lending a returned object literal.

---
 package.json                      |  2 +-
 rhino_modules/jsdoc/src/parser.js | 20 ++++++++++++++------
 2 files changed, 15 insertions(+), 7 deletions(-)

diff --git a/package.json b/package.json
index 7c1d746e..ccc591ae 100644
--- a/package.json
+++ b/package.json
@@ -1,7 +1,7 @@
 {
 	"name": "JSDoc",
 	"version": "3.0.0alpha",
-	"revision": "1319148880850",
+	"revision": "1319151616566",
 	"description": "An automatic documentation generator for javascript.",
 	"keywords": [ "documentation", "javascript" ],
 	"licenses": [
diff --git a/rhino_modules/jsdoc/src/parser.js b/rhino_modules/jsdoc/src/parser.js
index a89c1b84..dfd9ac72 100644
--- a/rhino_modules/jsdoc/src/parser.js
+++ b/rhino_modules/jsdoc/src/parser.js
@@ -103,7 +103,7 @@ exports.Parser.prototype._parseSourceCode = function(sourceCode, sourceName) {
         currentSourceName = sourceName = e.filename;
         
         sourceCode = pretreat(e.source);
-        
+               
         var ast = parserFactory().parse(sourceCode, sourceName, 1);
         ast.visit(
             new Packages.org.mozilla.javascript.ast.NodeVisitor({
@@ -119,12 +119,20 @@ exports.Parser.prototype._parseSourceCode = function(sourceCode, sourceName) {
 
 function pretreat(code) {
     return code
-        // merge adjacent doclets
-        .replace(/\*\/\/\*\*+/g, '@also')
-        // make lent objectliterals documentable by giving them a dummy name
-        .replace(/(\/\*\*[\s\S]*?@lends\b[\s\S]*?\*\/\s*)\{/g, '$1 ____ = {')
         // make starbangstar comments look like real jsdoc comments
-        .replace(/\/\*\!\*/g, '/**');
+        .replace(/\/\*\!\*/g, '/**')
+        
+        // make matching comment endings easier
+        .replace(/\*\//g, '»')
+        
+        // merge adjacent doclets
+        .replace(/»\/\*\*+/g, '@also')
+        // make lent objectliterals documentable by giving them a dummy name
+        .replace(/(\/\*\*[^»]*?@lends\b[^»]*?»\s*)\{/g, '$1 ____ = {') // like return @lends {
+        .replace(/(\/\*\*[^»]*?@lends\b[^»]*?»)(\s*)return(\s*)\{/g, '$2$3 return $1 ____ = {') // like @lends return {
+        
+        // make matching comment endings harder
+        .replace(/»/g, '*/');
 }
 
 /**