Merge pull request #66 from RamonEsteveCuevas/issue-65

Comments inside the package/type/view definition so they exist inside the database

lib/pmd.js

@@ -56,6 +56,47 @@ 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
  *
@@ -90,7 +131,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

src/packages/subfolder/package_comment_inside_db.pks

@@ -0,0 +1,76 @@
+create or replace package package_comment_inside_db
+  /**
+   * Description about the package itself. This can be compiled inside the database because it exists between the create or replace and end of the package.
+   *
+   * @author Ramon Esteve Cuevas
+   * @created 13/03/2017
+   */
+is
+
+  /**
+   * @constant gc_test_constant            A string test constant variable
+   * @constant gc_another_const            A number test constant variable using 'default' as assignment target
+   */
+  gc_test_constant    constant varchar2(30) := 'Test constant';
+  gc_another_const    constant number(10,1) default 10.1;
+
+  /**
+   * @type g_table_type       A test table type
+   */
+  type g_table_type is table of pls_integer index by varchar2(30);
+
+  /**
+   * @var g_string_var          A test variable which is a string and have a limited amount of characters
+   * @var g_number_var          A number variable without a restriction and using the ':=' as assignment target
+   * @var g_number_limited      A number which needs to have 1 decimal
+   * @var g_test_object         A variable of the Object type: "test_object"
+   * @var g_table_type_var      A variable which if of table type: "g_table_type"
+   */
+  g_string_var       varchar2(100) default 'Test variable';
+  g_number_var       number        := 123456;
+  g_number_limited   number(10, 1) default 10.1;
+  g_test_object      test_object   default new test_object();
+  g_table_type_var   g_table_type;
+
+  /**
+   * @exception g_no_data_found  A new no_data_found exception!
+   */
+  g_no_data_found   exception;
+  pragma            exception_init(g_no_data_found, -20001);
+
+  /**
+   * A cursor may also be inside a package header.
+   * Selects the value of p_test_param from dual
+   *
+   * @param p_test_param    A test parameter which will also be returned inside the cursor
+   */
+  cursor g_test_cur(p_test_param in varchar2) is
+    select p_test_param
+    from   dual;
+
+
+  /**
+   * Returns true/false if APEX developer is enable
+   * Supports both APEX 4 and 5 formats
+   *
+   * @issue #12 Initial creation
+   * @issue 23 Some major update
+   * @issue 46
+   *
+   * @example
+   * select *
+   * into l_temp
+   * from dual;
+   *
+   * @param p_app_id APEX application ID
+   * @param p_page_id APEX page ID
+   * @param p_session_id
+   *
+   * @author Martin Giffy D''Souza
+   * @created 29-Dec-2015
+   * @return true/false
+   */
+  function is_developer return boolean;
+
+end package_comment_inside_db;
+/

src/types/test_type_in_db.tps

@@ -0,0 +1,12 @@
+create or replace type test_type_in_db force
+  /**
+   * A SQL Object type which holds variables and can be used within the SQL engine
+   *
+   * The variables and function will not be documented. Only the global description has been included
+   */
+as object (
+
+   test_varchar      varchar2(4000)
+  ,test_number       number
+
+) not final;

src/views/test_view_in_db.vw

@@ -0,0 +1,9 @@
+create or replace view test_view_in_db
+  /**
+   * Selects from a 'test_string' from dual
+   *
+   * The Types/Constants/Variables and Exceptions may be removed from the HTML/MD page because it is not available in this context
+   */
+as
+  select 'test_string'
+  from   dual;