glob-docs - npm Package Compare versions

Comparing version 0.0.10-alpha to 0.0.11-alpha

package.json

 {
   "name": "glob-docs",
-  "version": "0.0.10-alpha",
+  "version": "0.0.11-alpha",
   "description": "",
@@ -5,0 +5,0 @@ "main": "index.js",

src/blobdocs.js

@@ -18,2 +18,3 @@ /*!
   CODE: require('./doctags/code'),
+  OPT: require('./doctags/option'),
   OPTION: require('./doctags/option'),
@@ -20,0 +21,0 @@ TODO: require('./doctags/todo'),

src/buildDocs.js

@@ -8,3 +8,2 @@ const fs = require('fs');
   for(let tagId in source) {
-
     const docTag = blobDocs._docTagsById[tagId];
@@ -16,3 +15,3 @@
     const { sourceFile } = node;
-    let rendered = source[tagId];
+    const rendered = source[tagId];
 
@@ -30,3 +29,2 @@ if (!sourceFile) continue;
     let currentContent = metatags.codeSource;
-
     let oldContent = '';
@@ -43,3 +41,3 @@
     let newContent = [openDocTag, rendered, closeDocTag].join('\n');
-
+    
     // NOTE: This is not replacing globally, so
@@ -46,0 +44,0 @@ // it will replace one token by time (each loop).

src/doctags/default.js

 const utils = require('./utils');
 const DocTag = require('./docTag');
-
-const DOC_TAG = '@DOC|';
 const DOC_TAG_TYPE = 'TEXT';
@@ -6,0 +4,0 @@

src/doctags/option.js

 const utils = require('./utils');
 const DocTag = require('./docTag');
+const Constants = require('./contants');
 
+/**
+ * When we want to specify a option name.
+ * OPTION:[my_opt_name]: My Description here.
+ */
+const OPT_NAME_PATTERN = new RegExp(/\[([^\]]+)\]/);
+
+const OPT_MACROS = [
+  "LINE",
+  "BELOW"
+];
+
 function merge({docTag, blobDocs}) {
@@ -22,10 +34,44 @@ const { tagValue } = docTag.node;
   docTag.setValue('comments', newCommentsLines.join(' '));
+  let tagValueRegex = tagValue.value.match(OPT_NAME_PATTERN);
+  let finalTagValue = null;
 
-  let tagValueRegex = tagValue.value.match(/\[([^\]]+)\]/);
+  /**
+   * Check if could find regular option with given name.
+   */
+  if (tagValueRegex && tagValueRegex.length >= 2) {
+    // it always must be the second array item
+    finalTagValue = tagValueRegex[1];
+  }
 
-  if(!tagValueRegex) {
+  if (!finalTagValue) {
+    // check if user are using macro
+    const foundMacro = OPT_MACROS.find(macro => tagValue.value.toUpperCase().startsWith(`${macro}:`));
+
+    /**
+     * The "macro" that gets the same line and transform it to an option name. 
+     */
+    if (foundMacro === 'LINE') {
+      const lineParts = docTag.node.code.split(Constants.DOC_TAG);
+      const optionName = lineParts[0].trim();
+      const findCommentCharacter = ["#", "//", "/*", "/", ";", "<!--"].find(x => optionName.endsWith(x));
+      docTag.setValue('comments', docTag.node.code.split(new RegExp(`${foundMacro}:`, 'i'))[1]);
+      finalTagValue = optionName.replace(new RegExp(findCommentCharacter + '$'), '');
+    }
+
+    if (foundMacro === 'BELOW') {
+      const nextLineValue = docTag.node.sourceFile.sourceCodeLines[docTag.node.lineNum];
+      if (nextLineValue.trim() === '') {
+        throw new Error(`The line below tag "@DOC|OPTION:BELOW" can not be empty. File: ${docTag.node.filename}:${docTag.node.lineNum}`);
+      }
+      docTag.setValue('comments', docTag.node.code.split(new RegExp(`${foundMacro}:`, 'i'))[1]);
+      finalTagValue = nextLineValue;
+    }
+  }
+
+  if(!finalTagValue) {
     throw new Error(`Invalid option name: ${tagValue.value}. Syntax usage: @DOC|OPTION:[my-var] or @DOC|OPTION:[my-var](default=value)`);
   }
 
-  docTag.setValue('tagValue', tagValueRegex[1]);
+  
+  docTag.setValue('tagValue', finalTagValue);
 
@@ -32,0 +78,0 @@ // Update parent nodes

src/renders/markdown.js

@@ -10,20 +10,22 @@ function createLink(childTag, label, options) {
 
+const OPTION = ({ options, docTag }) => {
+  if (docTag.options.root) {
+    let table = [
+      ' Option | Description',
+      '--------|------------'
+    ];
+    docTag.children.forEach(childTag => {
+      const {tagValue, comments} = childTag.metatags;
+      const filelink = createLink(childTag, tagValue, options);
+      table.push(`${filelink} | ${comments}`);
+    });
+    return table.join('\n');
+  }
+  return '';
+};
+
 module.exports = {
-  OPTION: ({ options, docTag }) => {
-    if (docTag.options.root) {
-      let table = [
-        ' Option | Description',
-        '--------|------------'
-      ];
+  OPTION,
+  OPT: OPTION, // options alias
 
-      docTag.children.forEach(childTag => {
-        const {tagValue, comments} = childTag.metatags;
-        const filelink = createLink(childTag, tagValue, options);
-        table.push(`${filelink} | ${comments}`);
-      });
-
-      return table.join('\n');
-    }
-    return '';
-  },
   /***
@@ -30,0 +32,0 @@ * It renders syntax highligh code.

test/fixtures/README.md

@@ -17,3 +17,3 @@ <!-- @DOC|INSERT:START(type=TODO) -->
 ###### 1.1.1.1 - another section
-File: [test/fixtures/demo-node.js:21](test/fixtures/demo-node.js#L21)
+<sub>File: <a href="test/fixtures/demo-node.js#L21">test/fixtures/demo-node.js:21</a></sub>
 ```js
@@ -28,9 +28,9 @@ function MyFunc1() {
 ###### 2.1.1.1 - another section
-File: [test/fixtures/demo-node.js:33](test/fixtures/demo-node.js#L33)
+<sub>File: <a href="test/fixtures/demo-node.js#L33">test/fixtures/demo-node.js:33</a></sub>
 ```php
- function MyFunc2() {
-  return 'my-code';
-}
+function MyFunc2() {
+ return 'my-code';
+
 ```
-File: [test/fixtures/demo-python.py:1](test/fixtures/demo-python.py#L1)
+<sub>File: <a href="test/fixtures/demo-python.py#L1">test/fixtures/demo-python.py:1</a></sub>
 ```js
@@ -40,10 +40,29 @@ def example(a, b):
 ```
+## TODO
+- [ ] - [ It should do something like that 1](test/fixtures/demo-terraform.tf#L1)
+- [x] - [ It should do something like that 1](test/fixtures/demo-terraform.tf#L2)
+- [x] - [ It should do something like that 1](test/fixtures/demo-terraform.tf#L3)
 ## Cluster Autoscaler
-File: [test/fixtures/demo-yml.yaml:3](test/fixtures/demo-yml.yaml#L3)
+<sub>File: <a href="test/fixtures/demo-yml.yaml#L3">test/fixtures/demo-yml.yaml:3</a></sub>
 ```js
-  - Apple
-  - Orange
-  - Strawberry
-  - Mango
+- Apple
+- Orange
+- Strawberry
+- Mango
 ```
+## Dependencies
+
+
+
+
+ Option | Description
+--------|------------
+<a href="test/fixtures/requirements.txt#L3">django==4.2.3               </a> |  This is my commentasdasdasd as dasdasdasadsdasads
+<a href="test/fixtures/requirements.txt#L4">Pillow==10.0.0              </a> |  This is my commentasdasdasd as dasdasdasadsdasads
+<a href="test/fixtures/requirements.txt#L5">django-extensions==3.2.1    </a> |  This is my commentasdasdasd as dasdasdasadsdasads
+<a href="test/fixtures/requirements.txt#L6">django-debug-toolbar==3.7.0 </a> |  This is my commentasdasdasd as dasdasdasadsdasads
+
+
+
+
 <!-- @DOC|INSERT:END -->

No alert changes

Improved metrics

Total package byte prevSize

33604

increased by10.03%

Number of package files

25

increased by8.7%

Lines of code

892

increased by4.94%

No dependency changes