documentary - npm Package Compare versions

Comparing version 1.34.2 to 1.34.3

build/components/Typedef/index.js

@@ -61,2 +61,3 @@ const { h } = require('preact');
       const res = type.toMarkdown(allTypes, opts)
+      res.examples = type.examples
       return res
@@ -66,3 +67,3 @@ }
     const table = makeMethodTable(type, allTypes, opts)
-    return { LINE, table }
+    return { LINE, table, examples: type.examples }
   })
@@ -77,8 +78,8 @@ // found those imports that will be flattened
   const ttt = tt.map((s, i) => {
-    const { LINE, table: type, displayInDetails } = s
+    const { LINE, table: type, displayInDetails, examples } = s
     const isObject = typeof type == 'object' // table can be empty string, e.g., ''
 
-    const ch = isObject ?       h(Narrow,{...type,key:i,
+    const ch = isObject ?        h(Narrow,{...type,key:i,
       documentary:documentary, allTypes:allTypes, opts:opts,
-      slimFunctions:slimFunctions
+      slimFunctions:slimFunctions, examples:examples
     }) : type
@@ -115,5 +116,7 @@ if (displayInDetails) {
  * @param {boolean} opts.const Whether the type is a constructor or interface.
+ * @param {string[]} opts.examples Examples for the constructor.
+ * @param {boolean} opts.constr Whether this is a table for the interface/constructor.
  */
 const Narrow = ({ props, anyHaveDefault, documentary, constr, allTypes, opts,
-  slimFunctions }) => {
+  slimFunctions, examples }) => {
   const md = (name, afterCutLinks) => {
@@ -130,5 +133,9 @@ return md2html({ documentary, children: [name], afterCutLinks })
     props.reduce((acc, { name, typeName, de, d, prop }) => {
+      if (name == 'constructor') prop.examples = examples
       let desc = (prop.args && !slimFunctions) ? makeMethodTable(prop, allTypes, opts, {
         indent: '', join: '<br/>\n', preargs: '<br/>\n',
       }) : de
+      if (examples.length) {
+        desc += `\n${makeExamples(prop.examples)}`
+      }
       const hasCodes = new RegExp(codeRe.source, codeRe.flags).test(prop.args ? desc : prop.description)
@@ -139,4 +146,8 @@ desc = desc + '\n  '
       const { optional, aliases, static: isStatic } = prop
-      const a = optional ? aliases : aliases.map(al => `${al}*`)
-      const n = [name, ...a]
+      const n = aliases.reduce((ac, al) => {
+        if (!constr && !optional) al = `${al}*`
+        // eslint-disable-next-line react/jsx-key
+        ac.push([al, (h('sup',{},h('em',{},`alias`)))])
+        return ac
+      }, [name])
       const isMethodCol = anyHaveDefault && prop.args
@@ -146,5 +157,10 @@ const row = (h('tr',{'key':name},'\n  ',
           n.reduce((ac, c, i, ar) => {
+            c = Array.isArray(c) ? c : [c]
+            let al
+            ;[c, al] = c
             if (isStatic) ac.push(h('kbd',{},`static`), ' ')
-            const u = constr ?  h('ins',{},c) : c
-            ac.push(constr || optional ? u :     h('strong',{},u))
+            // eslint-disable-next-line react/jsx-key
+            const u = constr ? [ h('ins',{},c), al] : [c]
+            if (constr || optional) ac.push(...u)
+            else ac.push(    h('strong',{},u))
             if (i < ar.length - 1) ac.push(h('br'))
@@ -166,3 +182,5 @@ return ac
         D = md(desc)
-        if (D) D = D.replace(/^/gm, '   ')
+        if (D) D = D
+          .replace(/^(?!%%_RESTREAM_CODE_REPLACEMENT)/gm, '   ')
+          .replace(/^ +$/gm, '')
         if (D) D = `\n${D}\n  `
@@ -187,3 +205,56 @@ }
 
+// from typal/src/Property.js
 /**
+ * Parse examples into string.
+ * When /// lines are found, they are not part of code blocks.
+ */
+const makeExamples = (examples) => {
+  const pp = []
+  examples.forEach((example) => {
+    const exampleLines = example.split('\n')
+    let currentComment = [], currentBlock = []
+    let state = '', newState
+    let eg = exampleLines.reduce((acc, current) => {
+      if (current.startsWith('///')) {
+        newState = 'comment'
+        currentComment.push(current)
+      } else {
+        newState = 'block'
+        currentBlock.push(current)
+      }
+      if (!state) state = newState
+      if (newState != state) {
+        if (newState == 'block') {
+          acc.push(currentComment.join('\n'))
+          currentComment = []
+        } else {
+          acc.push(currentBlock.join('\n'))
+          currentBlock = []
+        }
+        state = newState
+      }
+      return acc
+    }, [])
+    if (currentComment.length) {
+      eg.push(currentComment.join('\n'))
+    } else if (currentBlock.length) {
+      eg.push(currentBlock.join('\n'))
+    }
+    eg = eg.reduce((acc, e) => {
+      if (e.startsWith('///')) {
+        e = e.replace(/^\/\/\/\s+/gm, '')
+        acc.push(...e.split('\n'))
+      } else {
+        acc.push('```js')
+        acc.push(...e.split('\n'))
+        acc.push('```')
+      }
+      return acc
+    }, [])
+    pp.push(...eg)
+  })
+  return pp.join('\n')
+}
+
+/**
  * @suppress {nonStandardJsDocs}
@@ -190,0 +261,0 @@ * @typedef {import('typal/types').Type} Type

build/components/Typedef/index.jsx

@@ -60,2 +60,3 @@ const { SyncReplaceable } = require('../../../stdlib');
       const res = type.toMarkdown(allTypes, opts)
+      res.examples = type.examples
       return res
@@ -65,3 +66,3 @@ }
     const table = makeMethodTable(type, allTypes, opts)
-    return { LINE, table }
+    return { LINE, table, examples: type.examples }
   })
@@ -76,3 +77,3 @@ // found those imports that will be flattened
   const ttt = tt.map((s, i) => {
-    const { LINE, table: type, displayInDetails } = s
+    const { LINE, table: type, displayInDetails, examples } = s
     const isObject = typeof type == 'object' // table can be empty string, e.g., ''
@@ -82,3 +83,3 @@
       documentary={documentary} allTypes={allTypes} opts={opts}
-      slimFunctions={slimFunctions}
+      slimFunctions={slimFunctions} examples={examples}
     /> : type
@@ -115,5 +116,7 @@ if (displayInDetails) {
  * @param {boolean} opts.const Whether the type is a constructor or interface.
+ * @param {string[]} opts.examples Examples for the constructor.
+ * @param {boolean} opts.constr Whether this is a table for the interface/constructor.
  */
 const Narrow = ({ props, anyHaveDefault, documentary, constr, allTypes, opts,
-  slimFunctions }) => {
+  slimFunctions, examples }) => {
   const md = (name, afterCutLinks) => {
@@ -130,5 +133,9 @@ return md2html({ documentary, children: [name], afterCutLinks })
     {props.reduce((acc, { name, typeName, de, d, prop }) => {
+      if (name == 'constructor') prop.examples = examples
       let desc = (prop.args && !slimFunctions) ? makeMethodTable(prop, allTypes, opts, {
         indent: '', join: '<br/>\n', preargs: '<br/>\n',
       }) : de
+      if (examples.length) {
+        desc += `\n${makeExamples(prop.examples)}`
+      }
       const hasCodes = new RegExp(codeRe.source, codeRe.flags).test(prop.args ? desc : prop.description)
@@ -139,4 +146,8 @@ desc = desc + '\n  '
       const { optional, aliases, static: isStatic } = prop
-      const a = optional ? aliases : aliases.map(al => `${al}*`)
-      const n = [name, ...a]
+      const n = aliases.reduce((ac, al) => {
+        if (!constr && !optional) al = `${al}*`
+        // eslint-disable-next-line react/jsx-key
+        ac.push([al, (<sup><em>alias</em></sup>)])
+        return ac
+      }, [name])
       const isMethodCol = anyHaveDefault && prop.args
@@ -146,5 +157,10 @@ const row = (<tr key={name}>{'\n  '}
           {n.reduce((ac, c, i, ar) => {
+            c = Array.isArray(c) ? c : [c]
+            let al
+            ;[c, al] = c
             if (isStatic) ac.push(<kbd>static</kbd>, ' ')
-            const u = constr ? <ins>{c}</ins> : c
-            ac.push(constr || optional ? u : <strong>{u}</strong>)
+            // eslint-disable-next-line react/jsx-key
+            const u = constr ? [<ins>{c}</ins>, al] : [c]
+            if (constr || optional) ac.push(...u)
+            else ac.push(<strong>{u}</strong>)
             if (i < ar.length - 1) ac.push(<br/>)
@@ -167,3 +183,5 @@ return ac
         D = md(desc)
-        if (D) D = D.replace(/^/gm, '   ')
+        if (D) D = D
+          .replace(/^(?!%%_RESTREAM_CODE_REPLACEMENT)/gm, '   ')
+          .replace(/^ +$/gm, '')
         if (D) D = `\n${D}\n  `
@@ -189,3 +207,56 @@ }
 
+// from typal/src/Property.js
 /**
+ * Parse examples into string.
+ * When /// lines are found, they are not part of code blocks.
+ */
+const makeExamples = (examples) => {
+  const pp = []
+  examples.forEach((example) => {
+    const exampleLines = example.split('\n')
+    let currentComment = [], currentBlock = []
+    let state = '', newState
+    let eg = exampleLines.reduce((acc, current) => {
+      if (current.startsWith('///')) {
+        newState = 'comment'
+        currentComment.push(current)
+      } else {
+        newState = 'block'
+        currentBlock.push(current)
+      }
+      if (!state) state = newState
+      if (newState != state) {
+        if (newState == 'block') {
+          acc.push(currentComment.join('\n'))
+          currentComment = []
+        } else {
+          acc.push(currentBlock.join('\n'))
+          currentBlock = []
+        }
+        state = newState
+      }
+      return acc
+    }, [])
+    if (currentComment.length) {
+      eg.push(currentComment.join('\n'))
+    } else if (currentBlock.length) {
+      eg.push(currentBlock.join('\n'))
+    }
+    eg = eg.reduce((acc, e) => {
+      if (e.startsWith('///')) {
+        e = e.replace(/^\/\/\/\s+/gm, '')
+        acc.push(...e.split('\n'))
+      } else {
+        acc.push('```js')
+        acc.push(...e.split('\n'))
+        acc.push('```')
+      }
+      return acc
+    }, [])
+    pp.push(...eg)
+  })
+  return pp.join('\n')
+}
+
+/**
  * @suppress {nonStandardJsDocs}
@@ -192,0 +263,0 @@ * @typedef {import('typal/types').Type} Type

build/lib/rules/fork.js

 const { fork } = require('../../../stdlib');
 const { c } = require('../../../stdlib');
-const { resolve, join } = require('path');
+const { resolve, join, dirname } = require('path');
 const { resolveDependency } = require('../../../stdlib');
@@ -160,8 +160,8 @@ const { clearr } = require('../../../stdlib');
     let indicatrix = '.documentary/indicatrix.gif'
-    if (wiki) indicatrix = join(wiki, indicatrix)
     const imgPath = join(__dirname, '../../indicatrix.gif')
-    await clone(imgPath, '.documentary')
+    const to = wiki ? join(wiki, indicatrix) : indicatrix
+    await clone(imgPath, dirname(to))
     const t = cleared.replace(/<INDICATRIX_PLACEHOLDER>/g,
       `<a id="_ind${indicatrixId}" href="#_ind${indicatrixId}"><img src="${indicatrix}"></a>\n`)
-    indicatrixId ++
+    indicatrixId++
     return `<pre>${t}</pre>`
@@ -168,0 +168,0 @@ }

CHANGELOG.md

@@ -0,1 +1,8 @@
+## 16 December 2019
+
+### [1.34.3](https://github.com/artdecocode/documentary/compare/v1.34.2...v1.34.3)
+
+- [fix] Fix `indicatrix` for _Wiki_.
+- [feature] Embed examples for **Typal**'s slim functions.
+
 ## 9 December 2019
@@ -2,0 +9,0 @@

package.json

 {
   "name": "documentary",
-  "version": "1.34.2",
+  "version": "1.34.3",
   "description": "Documentation Compiler To Generate The Table Of Contents, Embed Examples With Their Output, Make Markdown Tables, Maintain Typedefs For JavaScript And README, Watch Changes To Push, Use Macros And Prettify API Titles.",
@@ -23,4 +23,4 @@ "main": "build",
     "b": "ALAMODE_ENV=build yarn-s src jsx b2",
-    "competent": "cp node_modules/competent/src/make-comps/init.js stdlib; cp node_modules/competent/src/make-comps/make-io.js stdlib; ",
-    "stdlib": "depack src/stdlib -o stdlib/index.js -a -c -p -s -O 2018 --source_map_include_content",
+    "competent": "alanode build-competent",
+    "stdlib": "depack src/stdlib -o stdlib/index.js -a -c -p -s --source_map_include_content",
     "src": "alamode src -o build -i bin/index.js,stdlib.js -s",
@@ -30,2 +30,3 @@ "jsx": "alamode build/components -o build/components -s -j -p",
     "build": "yarn-s b doc",
+    "up": "yarn-up -e preact",
     "args": "argufy types/arguments.xml -o src/bin/get-args.js"
@@ -123,6 +124,6 @@ },
   "dependencies": {
-    "alamode": "^3.2.0",
+    "alamode": "^3.3.0",
     "preact": "8.5.3",
-    "typal": "^1.22.9"
+    "typal": "^1.24.0"
   }
 }

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

472737

increased by0.97%

Lines of code

5432

increased by2.65%

Dependency changes

• Updatedalamode@^3.3.0

• Updatedtypal@^1.24.0