Merge pull request #58 from 365businessdev/dev

Version 1.1.1

CHANGELOG.md

@@ -128,7 +128,7 @@ All notable changes to the "AL XML Documentation" extension will be documented i
 - Fixed Issue [#27](https://github.com/365businessdev/vscode-alxmldocumentation/issues/27) - Inherit documentation for procedures implementing interface methods with underscore in object name
 - Added configuration parameter `InitializeALObjectCacheOnStartUp` to skip initialization while start-up.
 
-## [1.1.0] - 2021-04-16
+## [1.1.1] - 2021-04-21
 - Fixed Issue [#45](https://github.com/365businessdev/vscode-alxmldocumentation/issues/45) - Code analyzer rules for missing procedure XML documentation also reacts on 'procedure' in comments.
   > Thanks to @rvanbekkum for reporting.
 - Fixed missing example code in inherit procedure documentation.
@@ -146,4 +146,7 @@ All notable changes to the "AL XML Documentation" extension will be documented i
 - Fixed Issue [#52](https://github.com/365businessdev/vscode-alxmldocumentation/issues/52) - Analyze AL object asynchronously
   > Thanks to @TCMatthiasMartin for reporting.
 - Fixed Issue [#53](https://github.com/365businessdev/vscode-alxmldocumentation/issues/53) - Ignoring empty lines when creating MarkDown documentation
-  > Thanks to @horribleCodes for reporting.
+  > Thanks to @horribleCodes for reporting.
+- Fixed Issue [[#57](https://github.com/365businessdev/vscode-alxmldocumentation/issues/57)] - Multi-line documentation in markdown export
+- Add `event` support
+- Add `<code>` support for `<param>` and `<summary>`, including language specification.

README.md

@@ -1,15 +1,5 @@
 # XML Documentation Comments Support for AL language in Visual Studio Code
 
-> **Hi there!**
->
-> Please stop for a moment. Do you like our work and want to give some love back?<br>
-> No problem! We've created a fundraising event with which we would like to do something for a good cause.<br>
-> We would be very happy if you participate and support our **#LeaveNoOneBehind** campaign.
->
-> [![DonateNow]](https://www.betterplace.org/en/fundraising-events/37670-leavenoonebehind?utm_campaign=user_share&utm_medium=fepp_stats&utm_source=Link)
->
-> Thank you very much!
-
 Generate XML documentation comments for AL source code and create markdown documentation from it.
 
 ## Usage
@@ -28,13 +18,32 @@ In case you're implementing an AL interface object you are able to use inherit X
  - AL XML Documentation Interface Comment<br>Copies the original XML documentation comment from the interface object.<br>
 ![Apply XML documentation comment from interface object][InheritXmlDoc2]
 
-> **Important**<br>Current version of markdown export does not support inherit documentation. This feature will be released in a future version.
-
 ### Additional documentation features
 In addition to the regular documentation activity you can:
  - Add new lines in existing XML Documentation comment section. (`///` will automatically added.)
  - Use [Snippets](#Snippets) directly inside the XML Documentation comment section.
 
+#### Code documentation
+Sometimes it's useful to describe usage of parameters or procedures by simple example code. AL XML Documentation now supports `<code>` tags in `<param>` and `<summary>` documentations for procedures.
+
+> **Important**<br>Currently only one `<code>`-tag per `<param>` or `<summary>` is supported.
+
+![Use code-tag in Summary or Parameter description to explain usage][CodeDocumentation]
+
+Additionally you can specify the language by using the `lang`-attribute in the `<code>` tag:
+```js
+/// <summary>
+/// ...
+/// <code lang="json">
+/// {
+///     "key": "value"    
+/// }
+/// </code>
+/// </summary>
+```
+
+> **Important**<br>If you omit the `lang`-attribute, the default value is `al`.
+
 ### Generate markdown files from XML documentation comments
 The following commands are available to generate documentation files from XML documentation in AL source code:
 
@@ -190,6 +199,7 @@ This extension is only processing AL language source code files.
 | `local procedure` | ![Supported] |
 | `internal procedure` | ![Supported] |
 | `trigger` | ![Supported] |
+| `event` | ![Supported] |
 
 > **Note**<br>The purpose of the AL XML Documentation is to document your AL Source Code, not to document structures, controls or table fields.<br><br>Therefor it's currently not planned to add support for AL keywords, other the currently supported.
 
@@ -205,6 +215,7 @@ This extension is only processing AL language source code files.
 | `table extension` | ![Supported] |
 | `page extension` | ![Supported] |
 | `enum extension` | ![Supported] |
+| `controladdin` | ![Supported] |
 | `page customization` | ![NotSupport] |
 | `profile` | ![NotSupport] |
 
@@ -225,10 +236,20 @@ This extension is only processing AL language source code files.
 ## License
 This extension is licensed under the [MIT License](https://github.com/365businessdev/vscode-alxmldocumentation/blob/dev/LICENSE.txt).
 
-## Known Issues
+> **Hi there!**
+>
+> Please stop for a moment. Do you like our work and want to give some love back?<br>
+> No problem! We've created a fundraising event with which we would like to do something for a good cause.<br>
+> We would be very happy if you participate and support our **#LeaveNoOneBehind** campaign.
+>
+> [![DonateNow]](https://www.betterplace.org/en/fundraising-events/37670-leavenoonebehind?utm_campaign=user_share&utm_medium=fepp_stats&utm_source=Link)
+>
+> Thank you very much!
 
+## Known Issues
 ### 2020-04 - version 1.1.0
  - In large AL files (e.g. `Sales-Post` codeunit, +600 procedures) the analysis of the AL object can take several seconds. In this case the updating of diagnostic information and quick fixes is time delayed
+ - PDF Documentation Creation is failing under MacOS.
 
 
 [GenerateXmlDoc]: https://github.com/365businessdev/vscode-alxmldocumentation/blob/master/doc/V1.AddXmlDocComment.gif?raw=true "Generate context aware XML documentation comments"
@@ -237,6 +258,7 @@ This extension is licensed under the [MIT License](https://github.com/365busines
 [Setup]: https://github.com/365businessdev/vscode-alxmldocumentation/blob/master/doc/V1.Setup.png?raw=true "AL XML Documentation setup"
 [SummaryHover]: https://github.com/365businessdev/vscode-alxmldocumentation/blob/master/doc/HoverProcedureDescription.gif?raw=true  "Procedure documentation on hover"
 [DiagnosticsQuickFix]: https://github.com/365businessdev/vscode-alxmldocumentation/blob/master/doc/ALCheckDocumentationDiagnosticsQuickFix.gif?raw=true  "Diagnostics and Quick Fix"
+[CodeDocumentation]: https://raw.githubusercontent.com/365businessdev/vscode-alxmldocumentation/dev/doc/CodeDocumentation.png?raw=true "Use code-tag in Summary or Parameter description to explain usage"
 [DonateNow]: https://github.com/365businessdev/vscode-alxmldocumentation/blob/dev/doc/donate.png?raw=true  "Donate at betterplace.org"
 [Supported]: https://cdn4.iconfinder.com/data/icons/icocentre-free-icons/137/f-check_256-16.png "Supported"
 [NotSupport]: https://cdn2.iconfinder.com/data/icons/circular%20icons/no.png "Not Supported"

package.json

@@ -3,7 +3,7 @@
 	"displayName": "AL XML Documentation",
 	"description": "Generate XML documentation comments for AL source code and create markdown documentation from it.",
 	"publisher": "365businessdevelopment",
-	"version": "1.1.0",
+	"version": "1.1.1",
 	"icon": "res/icon.png",
 	"author": {
 		"name": "Christoph Krieg",
@@ -249,7 +249,7 @@
 		"@types/fs-extra": "^9.0.11",
 		"@types/glob": "^7.1.3",
 		"@types/mocha": "^7.0.2",
-		"@types/node": "^13.13.48",
+		"@types/node": "^13.13.49",
 		"@types/vscode": "^1.55.0",
 		"@typescript-eslint/eslint-plugin": "^2.34.0",
 		"@typescript-eslint/parser": "^2.34.0",

src/Controller.ts

@@ -44,7 +44,7 @@ export class Controller {
                     let allFiles = await workspace.findFiles(new RelativePattern(validPath, '**/*.al'), undefined, undefined, token);
                     let relevantFileTasks = allFiles.map(async (file: Uri) => {
                         let content = await readFile(file.fsPath, 'utf-8');
-                        if (content.match(/(procedure|trigger)\s+(.*?)\(/gm)) {
+                        if (content.match(/(procedure|trigger|event)\s+(.*?)\(/gm)) {
                             return { uri: file, content: content };
                         }
 

src/util/ALDocCommentUtil.ts

@@ -163,6 +163,30 @@ export class ALDocCommentUtil {
             return;
         }
 
+        if ((jsonDocumentation.root.summary) && (jsonDocumentation.root.summary.code)) {
+            if (!jsonDocumentation.root.summary.value) {
+                jsonDocumentation.root.summary.value = '';
+            }
+            let codeTag: any = jsonDocumentation.root.summary.code;
+            if ((!codeTag.attr) || (!codeTag.attr.lang)) {
+                jsonDocumentation.root.summary.value += '\n```al\n' + codeTag + '\n```\n';
+            } else {
+                jsonDocumentation.root.summary.value += '\n```' + codeTag.attr.lang + '\n' + codeTag.value + '\n```\n';
+            }
+        }
+
+        if ((jsonDocumentation.root.param) && (jsonDocumentation.root.param.code)) {
+            if (!jsonDocumentation.root.param.value) {
+                jsonDocumentation.root.param.value = '';
+            }
+            let codeTag: any = jsonDocumentation.root.param.code;
+            if ((!codeTag.attr) || (!codeTag.attr.lang)) {
+                jsonDocumentation.root.param.value += '\n```al\n' + codeTag + '\n```\n';
+            } else {
+                jsonDocumentation.root.param.value += '\n```' + codeTag.attr.lang + '\n' + codeTag.value + '\n```\n';
+            }
+        }
+
         return jsonDocumentation.root;
     }
 

src/util/ALObjectDocumentationExport.ts

@@ -104,7 +104,7 @@ pdf_options:
             doc.WriteLine('<div class="page-break"></div>');
             doc.WriteLine();
             output.appendLine(`${StringUtil.GetTimestamp()} Exporting documentation for ${ALObjectType[alObject.Type]} ${alObject.Name} . . . `);
-            await ALObjectDocumentationExport.ExportObject(alObject, output, Configuration.IncludeProcedureDocumentationInObjectDocumentationFile(), doc);
+            await ALObjectDocumentationExport.ExportObject(alObject, output, true, doc);
         };
 
         try
@@ -179,15 +179,15 @@ pdf_options:
                     doc.WriteLine(` - [${alObject.Name}${alObject.ID !== undefined ? " (ID " + alObject.ID + ")" : ""}](${link})<br>`);
                     if (alObject.XmlDocumentation.Exists === XMLDocumentationExistType.Yes) {
                         let documentation = await alObject.GetDocumentationAsJsonObject();
-                        doc.WriteLine(`   &emsp;*${documentation.summary}*`);
+                        doc.WriteLine(`<ul id="object-description"><i>${documentation.summary}</i></ul>\n`);
                     }
                 }
             };
         }
         headingLevel--;
 
         // write app dependencies
-        if (appJson.dependencies.length !== 0) {
+        if ((appJson.dependencies) && (appJson.dependencies.length !== 0)) {
             doc.WriteLine();
             doc.WriteHeading('Dependencies', headingLevel);
             appJson.dependencies.forEach((alDependency: { name: string; publisher: string; version: string; }) => {

src/util/ALSyntaxUtil.ts

@@ -901,10 +901,14 @@ export class ALSyntaxUtil {
                     }
 
                     if (collect) {
+                        let docLine: string = line.trimLeft().replace('///','');
+                        if (docLine.substr(0, 1) === ' ') {
+                            docLine = docLine.substr(1);
+                        }
                         if (result.Documentation !== '') {
-                            result.Documentation = `${line.replace('///','').trim()}\r\n${result.Documentation}`;
+                            result.Documentation = `${docLine}\r\n${result.Documentation}`;
                         } else {
-                            result.Documentation = line.replace('///','').trim();
+                            result.Documentation = docLine;
                         }
                     }
 

src/util/markdown/MarkdownWriter.ts

@@ -87,6 +87,6 @@ export class MarkdownWriter {
      * @returns Default stylesheet definition .
      */
     public static GetDefaultStylesheet(): string {
-        return `.page-header{margin:0 auto;font-family: Segoe UI Semibold;font-size: 10px;}.page-footer{margin-left: 50px;font-family:Segoe UI;font-size:9px}h1{font-size:28px}h2{font-size:26px}h3{font-size:23px}h4{font-size:22px}h5{font-size:20px}table{width:100%}`;
+        return `.page-header{margin:0 auto;font-family: Segoe UI Semibold;font-size: 10px;}.page-footer{margin-left: 50px;font-family:Segoe UI;font-size:9px}h1{font-size:28px}h2{font-size:26px}h3{font-size:23px}h4{font-size:22px}h5{font-size:20px}table{width:100%}#object-description{margin-top:-10px;margin-bottom:0px;}`;
     }
 }

src/util/regex/ALRegEx.ts

@@ -6,8 +6,8 @@ export const FindALObjectRegEx: RegExp = /^(?<ObjectType>[A-Za-z]*)\b\s+((?<Obje
 /**
  * Regular Expressions to find AL Procedures in Source Code.
  */
-export const FindALProceduresRegEx: RegExp = /(?<!\/\/.*)((local|internal|protected)\s*)?(procedure|trigger)\s+(\")?(.+)\b(\")?\((.*|[^)]+)\).*(?<!\/\/.*)/mg;
-export const ALProcedureDefinitionRegEx: RegExp = /(?<!\/\/.*)(?<Access>(local|internal|protected)\s*)?(?<Type>(procedure|trigger))\s+(?<ProcedureName>(\")?(.+)\b(\")?)\((?<Params>(.*|[^)]+))\)(?<ReturnType>.*)(?<!\/\/.*)/m;
+export const FindALProceduresRegEx: RegExp = /(?<!\/\/.*)((local|internal|protected)\s*)?(procedure|trigger|event)\s+(\")?(.+)\b(\")?\((.*|[^)]+)\).*(?<!\/\/.*)/mg;
+export const ALProcedureDefinitionRegEx: RegExp = /(?<!\/\/.*)(?<Access>(local|internal|protected)\s*)?(?<Type>(procedure|trigger|event))\s+(?<ProcedureName>(\")?(.+)\b(\")?)\((?<Params>(.*|[^)]+))\)(?<ReturnType>.*)(?<!\/\/.*)/m;
 
 /**
  * Regular Expressions for AL Source Code.