Previous revert removed the fix that allowed Package global comment inside package spec

lib/pmd.js

@@ -54,6 +54,46 @@ pmd.validatePathRef = function(fullPath, objName){
   }
 }// validatePathRef
 
+/**
+ * Parses documentation between the global name and the "is"/"as" to a readable format (above the name of the package/view/type etc
+ *
+ * @example
+ * create or replace test_package
+ *   {Comment}
+ * is
+ *
+ * will be parsed to:
+ * {Comment}
+ * create or replace test_package is
+ */
+pmd.parseGlobalDescription = function(data) {
+  /*
+   regex to read the following:
+   create or replace test_package (force)
+   {Comment}
+   is
+   */
+  var globalCommentRegex = /((create)[\w\s]*\s(package|type|view)\s+([\w$]+\s*(force)?)\s*)(\/\*([^*]|[\r\n]|(\*+([^*\/]|[\r\n])))*\*+\/)(\s*(as|is|begin))/gi;
+
+  // Check if the file contains this type of comments
+  if(globalCommentRegex.exec(data)) {
+    var comments = data.split(globalCommentRegex);
+
+    /* comments[6] inside the array is the documentation itself, comments[1] -> create or replace {name}
+     Replace the following:
+     create or replace test_package (force)
+     {Comment}
+     is
+     To:
+     {Comment}
+     create or replace test_package is
+     */
+    data = data.replace(/((create)[\w\s]*\s(package|type|view)\s+([\w$]+\s*(force)?)\s*)(\/\*([^*]|[\r\n]|(\*+([^*\/]|[\r\n])))*\*+\/)/gi, comments[6] + "\n" + comments[1]);
+  }
+
+  // Return the new data
+  return data;
+}//parseGlobalDescription
 
 /**
  * Processes a PL/SQL file to extract the JavaDoc contents
@@ -89,7 +129,7 @@ pmd.processFile = function(file){
 
   debug.log('\nProcessing:', file.path);
 
-  content.data = fs.readFileSync(file.path,'utf8');
+  content.data = pmd.parseGlobalDescription(fs.readFileSync(file.path,'utf8'));
   content.json = dox.parseComments(content.data);
 
   content.entities = []; //Holds list of entities for the object
@@ -139,7 +179,7 @@ pmd.processFile = function(file){
     else {
       // debug.log('Incorrectly parsed entry:', jsonData.code);
       continue; // Skip this loop since we dont know what this is
-    }
+      }
 
     jsonData.tags.forEach(function(tag){
       switch (tag.type) {

templates/toc.md

@@ -1,5 +1,5 @@
 # {{toUpperCase projectDispName}}
 
 {{#each files}}
-- [{{toUpperCase name}}]({{fileName}})
+- [{{toUpperCase name}}]({{docFileName}})
 {{/each}}