Merge pull request #1 from ogobrecht/development

Development

README.md

@@ -9,48 +9,53 @@
 - [Example for multiple files](#example-for-multiple-files)
 - [Automation with a file watcher](#automation-with-a-file-watcher)
 - [Read more about npm scripts](#read-more-about-npm-scripts)
+- [SQL*Plus Special Characters](#sqlplus-special-characters)
+- [Markdown Headers](#markdown-headers)
 - [Changelog](#changelog)
 
 <!-- tocstop -->
 
+![Preview](preview.png)
+
 ## Description
 
 PLOC is a simple PL/SQL code to doc converter which supports comments written in Markdown and generates Markdown files ready to use for your documentation. It is a npm package and therefore written in JavaScript. Simple means here really simple - the converter is only about 120 lines of commented code. Here a short demo package spec which demonstrates the idea behind PLOC:
 
 ~~~sql
-CREATE OR REPLACE PACKAGE DEMO AUTHID current_user IS
+CREATE OR REPLACE PACKAGE demo AUTHID current_user IS
 c_demo_name CONSTANT VARCHAR2(30 CHAR) := 'A demo package for PLOC';
 /**
-PL/SQL Demo Package
+Your Leading Level One Header
+=============================
 
 You can use standard markdown here to describe your package, functions and procedures.
 
 - This is a list entry
 - A second one
 
-[A link](https://daringfireball.net/projects/markdown/basics).
+[A link to Markdown basics](https://daringfireball.net/projects/markdown/basics).
 **/
 
 
-FUNCTION to_zip (
-  p_file_collection IN apex_t_export_files -- The file collection to process with APEX_ZIP.
-) RETURN BLOB;
+FUNCTION demo_function (
+  p_num_param IN NUMBER,   -- Some short parameter description.
+  p_vc2_param IN VARCHAR2) -- Another parameter description.
+RETURN BLOB;
 /**
-Convert a file collection to a zip file.
+Description of the function.
 
 EXAMPLE
 
 ```sql
 DECLARE
-  l_zip BLOB;
+  l_result VARCHAR2(100);
 BEGIN
-    l_zip := plex.to_zip(plex.backapp(
-      p_app_id             => 100,
-      p_include_object_ddl => true
-    ));
-
-  -- do something with the zip file...
+  l_result := demo_function(
+    p_num_param => 100,
+    p_vc2_param => 'some text'));
+  -- do something with the result...
 END;
+{{/}}
 ```
 **/
 
@@ -61,85 +66,96 @@ END DEMO;
 - Anything else is ignored - if you want to include something in your docs, you have to provide a comment in the mentioned style after the relevant signature
 - In the comments you can provide standard Markdown - anything what the target system (GitHub for example) can convert to valid HTML (we do not generate the HTML here, only the Markdown file)
 - In the example above the constant `c_demo_name` is included in the docs - if you don't want this move the code behind the comment - you decide which globals are documented and which not
-- There is no parameter parsing: the converter prints for each found item the following informations
-  - A header (`# Package DEMO` or `## FUNCTION to_zip` in our example)
+- There is no parameter parsing: the converter prints for each item the following informations
+  - A header (`# Package demo` or `## FUNCTION demo_function` in our example)
   - The comment content
   - A paragraph containing the word `SIGNATURE`
   - The signature of the PACKAGE, FUNCTION, PROCEDURE, TYPE or TRIGGER wrapped in a code block
   - Depending on the number of items (configurable) a TOC is generated in front of the document
   - A "Do not edit directly..." HTML comment with the source file path info is also generated on top of the file
+- A leading level one header in the first comment (usually the package description) is used as the overall document header
 
 Many words... Here the converted output of our example package:
 
 ~~~md
-<!-- DO NOT EDIT THIS FILE DIRECTLY - it is generated from source file tests/demo.sql -->
+<!-- DO NOT EDIT THIS FILE DIRECTLY - it is generated from source file tests/demo.pks -->
 
-Package DEMO
-============
+Your Leading Level One Header
+=============================
 
-PL/SQL Demo Package
+Package demo
+------------
 
 You can use standard markdown here to describe your package, functions and procedures.
 
 - This is a list entry
 - A second one
 
-[A link](https://daringfireball.net/projects/markdown/basics).
+[A link to Markdown basics](https://daringfireball.net/projects/markdown/basics).
 
 SIGNATURE
 
 ```sql
-PACKAGE DEMO AUTHID current_user IS
+PACKAGE demo AUTHID current_user IS
 c_demo_name CONSTANT VARCHAR2(30 CHAR) := 'A demo package for PLOC';
 ```
 
 
-Function to_zip
----------------
+Function demo_function
+----------------------
 
-Convert a file collection to a zip file.
+Description of the function.
 
 EXAMPLE
 
 ```sql
 DECLARE
-  l_zip BLOB;
+  l_result VARCHAR2(100);
 BEGIN
-    l_zip := plex.to_zip(plex.backapp(
-      p_app_id             => 100,
-      p_include_object_ddl => true
-    ));
-
-  -- do something with the zip file...
+  l_result := demo_function(
+    p_num_param => 100,
+    p_vc2_param => 'some text'));
+  -- do something with the result...
 END;
+/
 ```
 
 SIGNATURE
 
 ```sql
-FUNCTION to_zip (
-  p_file_collection IN apex_t_export_files -- The file collection to process with APEX_ZIP.
-) RETURN BLOB;
+FUNCTION demo_function (
+  p_num_param IN NUMBER,   -- Some short parameter description.
+  p_vc2_param IN VARCHAR2) -- Another parameter description.
+RETURN BLOB;
 ```
 ~~~
 
 For a bigger example see the following two projects which are using PLOC for the generation of the README.md file:
 
-- [PL/SQL Export Utilities](https://github.com/ogobrecht/plex)
-  - [The package source code](https://github.com/ogobrecht/plex/blob/master/PLEX.pks)
-  - [The raw Markdown file generated by PLOC](https://raw.githubusercontent.com/ogobrecht/plex/master/README.md)
-  - [The README file rendered as HTML by GitHub](https://github.com/ogobrecht/plex/blob/master/README.md)
-- [Oracle Table API Generator](https://github.com/OraMUC/table-api-generator)
-  - [The package source code](https://github.com/OraMUC/table-api-generator/blob/master/OM_TAPIGEN.pks)
-  - [The raw Markdown file generated by PLOC](https://raw.githubusercontent.com/OraMUC/table-api-generator/master/README.md)
-  - [The README file rendered as HTML by GitHub](https://github.com/OraMUC/table-api-generator/blob/master/README.md)
+- [PL/SQL Export Utilities][plex]
+  - [The package source code][plexSpec]
+  - [The raw Markdown file generated by PLOC][plexReadme]
+  - [The README file rendered as HTML by GitHub][plexReadmeHTML]
+- [Oracle Table API Generator][tapigen]
+  - [The package source code][tapigenSpec]
+  - [The raw Markdown file generated by PLOC][tapigenReadme]
+  - [The README file rendered as HTML by GitHub][tapigenReadmeHTML]
+
+[plex]: https://github.com/ogobrecht/plex
+[plexSpec]: https://github.com/ogobrecht/plex/blob/master/PLEX.pks
+[plexReadme]: https://raw.githubusercontent.com/ogobrecht/plex/master/README.md
+[plexReadmeHTML]: https://github.com/ogobrecht/plex/blob/master/README.md
+[tapigen]: https://github.com/OraMUC/table-api-generator
+[tapigenSpec]: https://github.com/OraMUC/table-api-generator/blob/master/OM_TAPIGEN.pks
+[tapigenReadme]: https://raw.githubusercontent.com/OraMUC/table-api-generator/master/README.md
+[tapigenReadmeHTML]: https://github.com/OraMUC/table-api-generator/blob/master/README.md
 
 
 ## FAQ
 
 QUESTION: Why no JavaDoc compatible parameter desriptions?
 
-ANSWER: In my opinion this does NOT follow the DRY principle and is error prone. PL/SQL is a strong typed language. Anything you need to know is visible in the signature. There is no need to repeat the parameters in a formal way only to comment a little bit. For short comments you can put single line comments direct after the parameters (see parameter `p_file_collection` in function `to_zip` in the example above). If you need to write more refer to the Markdown main comment. On long parameter lists you will more easily follow the single line comments direct after the parameters then looking around between the signature and the formal JavaDoc comments.
+ANSWER: In my opinion this does NOT follow the DRY principle and is error prone. PL/SQL is a strong typed language. Anything you need to know is visible in the signature. There is no need to repeat the parameters in a formal way only to comment a little bit. For short comments you can put single line comments direct after the parameters (see  function `demo_function` in the example above). If you need to write more refer to the Markdown main comment. On long parameter lists you will more easily follow the single line comments direct after the parameters then looking around between the signature and the formal JavaDoc comments.
 
 QUESTION: Why do I need to put the comments below the signature?
 
@@ -192,7 +208,7 @@ Usage: ploc [options]
 
   -t, --toc:    How many items (methods including object/package name) the
                 code must have before a toc is included
-                (default is 4)
+                (default is 3)
 
   -h, --help:   Command line help
 
@@ -347,10 +363,47 @@ PLEX.pks => README.md
 - https://css-tricks.com/why-npm-scripts/
 
 
+## SQL*Plus Special Characters
+
+`/`, `#` and `@` are special SQL*Plus characters. If they occur as the first
+character in a line then SQL*Plus does some special functionality - independend
+from the occurence inside a comment or a string literal. So be warned - the
+minimum problem you will get is that compiling PL/SQL code in an SQL*Plus script
+will fail. The maximum problem under some circumstances is the [lost of data][example].
+
+To avoid these problems we have to escape the characters like so: `{{/}} {{#}} {{@}}`. 
+PLOC does unescape these characters when generating your markdown docs.
+
+[example]: http://www.oraclefindings.com/2016/08/16/sql-plus-hash-pound/)
+
+
+## Markdown Headers
+
+The generated doc is already structured with level one and level two headers. If you want
+to use Markdown headers in your comments then please use level three to level six headers.
+Please beware of the potential SQL*Plus issues described above. To avoid these you have
+to escape the first hash character like so:
+
+```md
+{{#}}## Level 3 Header
+{{#}}### Level 4 Header
+{{#}}#### Level 5 Header
+{{#}}##### Level 6 Header
+```
+
 
 ## Changelog
 
 
+### 0.6.0 - 2018-06-20
+
+- Improved generated document structure
+    - A leading level one header in the first comment (usually the package description) is used as the overall document header
+    - An eventually rendered TOC is following this overall header
+- PLOC does now unescape escaped special SQL*Plus characters (see section "SQL\*Plus Special Characters")
+- Change minimum number of items to render a TOC from 4 to 3
+
+
 ### 0.5.0 - 2018-12-23
 
 - Add "Do not edit..." message to generated files

package.json

@@ -1,13 +1,13 @@
 {
   "name": "ploc",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "PL/SQL code to doc converter",
   "main": "ploc.js",
   "bin": {
     "ploc": "ploc-cli.js"
   },
   "scripts": {
-    "test": "echo \"Please check output tests/*.md!\" && node ploc-cli.js -d -i 'tests/*.*(pks|sql)'",
+    "test": "echo \"Please check output tests/*.md!\" && node ploc-cli.js -d -i \"tests/*.*(pks|sql)\"",
     "build": "npx markdown-toc -i --maxdepth 2 README.md"
   },
   "repository": {
@@ -28,7 +28,7 @@
   },
   "homepage": "https://github.com/ogobrecht/ploc#readme",
   "dependencies": {
-    "glob": "^7.1.2",
+    "glob": "^7.1.4",
     "minimist": "^1.2.0"
   },
   "devDependencies": {

ploc-cli.js

@@ -36,16 +36,16 @@ ploc.opts.cliHelp = [
   '                {file} = in file name without extension',
   '',
   '  -t, --toc:    How many items (methods including object/package name) the',
-  '                code must have before a toc is included',
+  '                code must have before a TOC is included',
   '                (default is ' + ploc.opts.cliArgs.default.toc + ')',
   '',
   '  -h, --help:   Command line help',
   '',
   '  -d, --debug:  Write CLI arguments to console',
   '',
-  'Example 1: npx ploc --in \'**/*.pks\' --out {folder}{file}.md',
+  'Example 1: npx ploc --in "**/*.pks" --out {folder}{file}.md',
   'Example 2: npx ploc --out docs/{file}.md',
-  'Example 3: npx ploc -i \'**/*.*(pks|sql)\' -o docs/{file}.md -t 5',
+  'Example 3: npx ploc -i "**/*.*(pks|sql)" -o docs/{file}.md -t 5',
   'https://blog.npmjs.org/post/162869356040/introducing-npx-an-npm-package-runner',
   '',
 ].join('\n');