Add jsdoc for utils

2019-04-11 00:57:12 +09:00
parent aa9d48905f
commit 2d5585709d
9 changed files with 250 additions and 113 deletions
--- a/src/components/Charts/keyboard.vue
+++ b/src/components/Charts/keyboard.vue
@@ -53,103 +53,102 @@ export default {
        data.push((Math.sin(i / 5) * (i / 5 - 10) + i / 6) * 5)
        data2.push((Math.sin(i / 5) * (i / 5 + 10) + i / 6) * 3)
      }
-      this.chart.setOption(
-        {
-          backgroundColor: '#08263a',
-          grid: {
-            left: '5%',
-            right: '5%'
-          },
-          xAxis: [{
-            show: false,
-            data: xAxisData
-          }, {
-            show: false,
-            data: xAxisData
-          }],
-          visualMap: {
-            show: false,
-            min: 0,
-            max: 50,
-            dimension: 0,
-            inRange: {
-              color: ['#4a657a', '#308e92', '#b1cfa5', '#f5d69f', '#f5898b', '#ef5055']
-            }
-          },
-          yAxis: {
-            axisLine: {
-              show: false
-            },
-            axisLabel: {
-              textStyle: {
-                color: '#4a657a'
-              }
-            },
-            splitLine: {
-              show: true,
-              lineStyle: {
-                color: '#08263f'
-              }
-            },
-            axisTick: {
-              show: false
-            }
-          },
-          series: [{
-            name: 'back',
-            type: 'bar',
-            data: data2,
-            z: 1,
-            itemStyle: {
-              normal: {
-                opacity: 0.4,
-                barBorderRadius: 5,
-                shadowBlur: 3,
-                shadowColor: '#111'
-              }
-            }
-          }, {
-            name: 'Simulate Shadow',
-            type: 'line',
-            data,
-            z: 2,
-            showSymbol: false,
-            animationDelay: 0,
-            animationEasing: 'linear',
-            animationDuration: 1200,
-            lineStyle: {
-              normal: {
-                color: 'transparent'
-              }
-            },
-            areaStyle: {
-              normal: {
-                color: '#08263a',
-                shadowBlur: 50,
-                shadowColor: '#000'
-              }
-            }
-          }, {
-            name: 'front',
-            type: 'bar',
-            data,
-            xAxisIndex: 1,
-            z: 3,
-            itemStyle: {
-              normal: {
-                barBorderRadius: 5
-              }
-            }
-          }],
-          animationEasing: 'elasticOut',
-          animationEasingUpdate: 'elasticOut',
-          animationDelay(idx) {
-            return idx * 20
-          },
-          animationDelayUpdate(idx) {
-            return idx * 20
+      this.chart.setOption({
+        backgroundColor: '#08263a',
+        grid: {
+          left: '5%',
+          right: '5%'
+        },
+        xAxis: [{
+          show: false,
+          data: xAxisData
+        }, {
+          show: false,
+          data: xAxisData
+        }],
+        visualMap: {
+          show: false,
+          min: 0,
+          max: 50,
+          dimension: 0,
+          inRange: {
+            color: ['#4a657a', '#308e92', '#b1cfa5', '#f5d69f', '#f5898b', '#ef5055']
          }
-        })
+        },
+        yAxis: {
+          axisLine: {
+            show: false
+          },
+          axisLabel: {
+            textStyle: {
+              color: '#4a657a'
+            }
+          },
+          splitLine: {
+            show: true,
+            lineStyle: {
+              color: '#08263f'
+            }
+          },
+          axisTick: {
+            show: false
+          }
+        },
+        series: [{
+          name: 'back',
+          type: 'bar',
+          data: data2,
+          z: 1,
+          itemStyle: {
+            normal: {
+              opacity: 0.4,
+              barBorderRadius: 5,
+              shadowBlur: 3,
+              shadowColor: '#111'
+            }
+          }
+        }, {
+          name: 'Simulate Shadow',
+          type: 'line',
+          data,
+          z: 2,
+          showSymbol: false,
+          animationDelay: 0,
+          animationEasing: 'linear',
+          animationDuration: 1200,
+          lineStyle: {
+            normal: {
+              color: 'transparent'
+            }
+          },
+          areaStyle: {
+            normal: {
+              color: '#08263a',
+              shadowBlur: 50,
+              shadowColor: '#000'
+            }
+          }
+        }, {
+          name: 'front',
+          type: 'bar',
+          data,
+          xAxisIndex: 1,
+          z: 3,
+          itemStyle: {
+            normal: {
+              barBorderRadius: 5
+            }
+          }
+        }],
+        animationEasing: 'elasticOut',
+        animationEasingUpdate: 'elasticOut',
+        animationDelay(idx) {
+          return idx * 20
+        },
+        animationDelayUpdate(idx) {
+          return idx * 20
+        }
+      })
    }
  }
 }
--- a/src/components/DragSelect/index.vue
+++ b/src/components/DragSelect/index.vue
@@ -49,13 +49,13 @@ export default {
 </script>

 <style scoped>
-.drag-select >>> .sortable-ghost{
+.drag-select >>> .sortable-ghost {
  opacity: .8;
  color: #fff!important;
  background: #42b983!important;
 }

-.drag-select >>> .el-tag{
+.drag-select >>> .el-tag {
  cursor: pointer;
 }
 </style>
--- a/src/filters/index.js
+++ b/src/filters/index.js
@@ -1,6 +1,13 @@
 // set function parseTime,formatTime to filter
 export { parseTime, formatTime } from '@/utils'

+/**
+ * Show plural label if time is plural number
+ *
+ * @param {number} time
+ * @param {string} label
+ * @return {string}
+ */
 function pluralize(time, label) {
  if (time === 1) {
    return time + label
@@ -8,6 +15,9 @@ function pluralize(time, label) {
  return time + label + 's'
 }

+/**
+ * @param {number} time
+ */
 export function timeAgo(time) {
  const between = Date.now() / 1000 - Number(time)
  if (between < 3600) {
@@ -19,7 +29,11 @@ export function timeAgo(time) {
  }
 }

-/* 数字 格式化*/
+/**
+ * 数字 格式化
+ * @param {number} num
+ * @param {number} digits
+ */
 export function numberFormatter(num, digits) {
  const si = [
    { value: 1E18, symbol: 'E' },
@@ -37,6 +51,9 @@ export function numberFormatter(num, digits) {
  return num.toString()
 }

+/**
+ * @param {number} num
+ */
 export function toThousandFilter(num) {
  return (+num || 0).toString().replace(/^-?\d+/g, m => m.replace(/(?=(?!\b)(\d{3})+$)/g, ','))
 }
--- a/src/layout/index.vue
+++ b/src/layout/index.vue
@@ -24,12 +24,12 @@ import { mapState } from 'vuex'
 export default {
  name: 'Layout',
  components: {
-    RightPanel,
-    Navbar,
-    Sidebar,
    AppMain,
-    TagsView,
-    Settings
+    Navbar,
+    RightPanel,
+    Settings,
+    Sidebar,
+    TagsView
  },
  mixins: [ResizeMixin],
  computed: {
--- a/src/utils/index.js
+++ b/src/utils/index.js
@@ -2,6 +2,12 @@
 * Created by jiachenpan on 16/11/18.
 */

+/**
+ * Parse the time to string
+ * @param {(Object|string|number)} time
+ * @param {string} cFormat
+ * @returns {string}
+ */
 export function parseTime(time, cFormat) {
  if (arguments.length === 0) {
    return null
@@ -40,6 +46,11 @@ export function parseTime(time, cFormat) {
  return time_str
 }

+/**
+ * @param {number} time
+ * @param {string} option
+ * @returns {string}
+ */
 export function formatTime(time, option) {
  if (('' + time).length === 10) {
    time = parseInt(time) * 1000
@@ -78,7 +89,11 @@ export function formatTime(time, option) {
  }
 }

-// 格式化时间
+/**
+ * 格式化时间
+ * @param {string} url
+ * @returns {Object}
+ */
 export function getQueryObject(url) {
  url = url == null ? window.location.href : url
  const search = url.substring(url.lastIndexOf('?') + 1)
@@ -95,7 +110,7 @@ export function getQueryObject(url) {
 }

 /**
- * @param {Sting} input value
+ * @param {string} input value
 * @returns {number} output value
 */
 export function byteLength(str) {
@@ -110,6 +125,10 @@ export function byteLength(str) {
  return s
 }

+/**
+ * @param {Array} actual
+ * @returns {Array}
+ */
 export function cleanArray(actual) {
  const newArray = []
  for (let i = 0; i < actual.length; i++) {
@@ -120,6 +139,10 @@ export function cleanArray(actual) {
  return newArray
 }

+/**
+ * @param {Object} json
+ * @returns {Array}
+ */
 export function param(json) {
  if (!json) return ''
  return cleanArray(
@@ -130,6 +153,10 @@ export function param(json) {
  ).join('&')
 }

+/**
+ * @param {string} url
+ * @returns {Object}
+ */
 export function param2Obj(url) {
  const search = url.split('?')[1]
  if (!search) {
@@ -146,16 +173,24 @@ export function param2Obj(url) {
  )
 }

+/**
+ * @param {string} val
+ * @returns {string}
+ */
 export function html2Text(val) {
  const div = document.createElement('div')
  div.innerHTML = val
  return div.textContent || div.innerText
 }

+/**
+ * Merges two objects, giving the last one precedence
+ *
+ * @param {Object} target
+ * @param {(Object|Array)} source
+ * @returns {Object}
+ */
 export function objectMerge(target, source) {
-  /* Merges two  objects,
-     giving the last one precedence */
-
  if (typeof target !== 'object') {
    target = {}
  }
@@ -173,6 +208,10 @@ export function objectMerge(target, source) {
  return target
 }

+/**
+ * @param {HTMLElement} element
+ * @param {string} className
+ */
 export function toggleClass(element, className) {
  if (!element || !className) {
    return
@@ -228,6 +267,10 @@ export const pickerOptions = [
  }
 ]

+/**
+ * @param {string} type
+ * @returns {Date}
+ */
 export function getTime(type) {
  if (type === 'start') {
    return new Date().getTime() - 3600 * 1000 * 24 * 90
@@ -236,6 +279,12 @@ export function getTime(type) {
  }
 }

+/**
+ * @param {Function} func
+ * @param {number} wait
+ * @param {boolean} immediate
+ * @return {*}
+ */
 export function debounce(func, wait, immediate) {
  let timeout, args, context, timestamp, result

@@ -275,6 +324,8 @@ export function debounce(func, wait, immediate) {
 * This is just a simple version of deep copy
 * Has a lot of edge cases bug
 * If you want to use a perfect deep copy, use lodash's _.cloneDeep
+ * @param {Object} source
+ * @returns {Object}
 */
 export function deepClone(source) {
  if (!source && typeof source !== 'object') {
@@ -291,22 +342,50 @@ export function deepClone(source) {
  return targetObj
 }

+/**
+ * @param {Array} arr
+ * @returns {Array}
+ */
 export function uniqueArr(arr) {
  return Array.from(new Set(arr))
 }

+/**
+ * @returns {string}
+ */
 export function createUniqueString() {
  const timestamp = +new Date() + ''
  const randomNum = parseInt((1 + Math.random()) * 65536) + ''
  return (+(randomNum + timestamp)).toString(32)
 }

+/**
+ * Check if an element has a class
+ *
+ * @param {HTMLElement} elm
+ * @param {string} cls
+ * @returns {boolean}
+ */
 export function hasClass(ele, cls) {
  return !!ele.className.match(new RegExp('(\\s|^)' + cls + '(\\s|$)'))
 }
+
+/**
+ * Add class to element
+ *
+ * @param {HTMLElement} elm
+ * @param {string} cls
+ */
 export function addClass(ele, cls) {
  if (!hasClass(ele, cls)) ele.className += ' ' + cls
 }
+
+/**
+ * Remove class from element
+ *
+ * @param {HTMLElement} elm
+ * @param {string} cls
+ */
 export function removeClass(ele, cls) {
  if (hasClass(ele, cls)) {
    const reg = new RegExp('(\\s|^)' + cls + '(\\s|$)')
--- a/src/utils/openWindow.js
+++ b/src/utils/openWindow.js
@@ -5,7 +5,6 @@
 * @param {Number} w
 * @param {Number} h
 */
-
 export default function openWindow(url, title, w, h) {
  // Fixes dual-screen position                            Most browsers       Firefox
  const dualScreenLeft = window.screenLeft !== undefined ? window.screenLeft : screen.left
--- a/src/utils/scrollTo.js
+++ b/src/utils/scrollTo.js
@@ -12,7 +12,10 @@ var requestAnimFrame = (function() {
  return window.requestAnimationFrame || window.webkitRequestAnimationFrame || window.mozRequestAnimationFrame || function(callback) { window.setTimeout(callback, 1000 / 60) }
 })()

-// because it's so fucking difficult to detect the scrolling element, just move them all
+/**
+ * Because it's so fucking difficult to detect the scrolling element, just move them all
+ * @param {number} amount
+ */
 function move(amount) {
  document.documentElement.scrollTop = amount
  document.body.parentNode.scrollTop = amount
@@ -23,6 +26,11 @@ function position() {
  return document.documentElement.scrollTop || document.body.parentNode.scrollTop || document.body.scrollTop
 }

+/**
+ * @param {number} to
+ * @param {number} duration
+ * @param {Function} callback
+ */
 export function scrollTo(to, duration, callback) {
  const start = position()
  const change = to - start
--- a/src/utils/validate.js
+++ b/src/utils/validate.js
@@ -1,41 +1,72 @@
 /**
 * Created by jiachenpan on 16/11/18.
 */
-
+/**
+ * @param {string} path
+ * @returns {Boolean}
+ */
 export function isExternal(path) {
  return /^(https?:|mailto:|tel:)/.test(path)
 }

+/**
+ * @param {string} str
+ * @returns {Boolean}
+ */
 export function validUsername(str) {
  const valid_map = ['admin', 'editor']
  return valid_map.indexOf(str.trim()) >= 0
 }

+/**
+ * @param {string} url
+ * @returns {Boolean}
+ */
 export function validURL(url) {
  const reg = /^(https?|ftp):\/\/([a-zA-Z0-9.-]+(:[a-zA-Z0-9.&%$-]+)*@)*((25[0-5]|2[0-4][0-9]|1[0-9]{2}|[1-9][0-9]?)(\.(25[0-5]|2[0-4][0-9]|1[0-9]{2}|[1-9]?[0-9])){3}|([a-zA-Z0-9-]+\.)*[a-zA-Z0-9-]+\.(com|edu|gov|int|mil|net|org|biz|arpa|info|name|pro|aero|coop|museum|[a-zA-Z]{2}))(:[0-9]+)*(\/($|[a-zA-Z0-9.,?'\\+&%$#=~_-]+))*$/
  return reg.test(url)
 }

+/**
+ * @param {string} str
+ * @returns {Boolean}
+ */
 export function validLowerCase(str) {
  const reg = /^[a-z]+$/
  return reg.test(str)
 }

+/**
+ * @param {string} str
+ * @returns {Boolean}
+ */
 export function validUpperCase(str) {
  const reg = /^[A-Z]+$/
  return reg.test(str)
 }

+/**
+ * @param {string} str
+ * @returns {Boolean}
+ */
 export function validAlphabets(str) {
  const reg = /^[A-Za-z]+$/
  return reg.test(str)
 }

+/**
+ * @param {string} email
+ * @returns {Boolean}
+ */
 export function validEmail(email) {
  const reg = /^(([^<>()\[\]\\.,;:\s@"]+(\.[^<>()\[\]\\.,;:\s@"]+)*)|(".+"))@((\[[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\])|(([a-zA-Z\-0-9]+\.)+[a-zA-Z]{2,}))$/
  return reg.test(email)
 }

+/**
+ * @param {string} str
+ * @returns {Boolean}
+ */
 export function isString(str) {
  if (typeof str === 'string' || str instanceof String) {
    return true
@@ -43,6 +74,10 @@ export function isString(str) {
  return false
 }

+/**
+ * @param {Array} arg
+ * @returns {Boolean}
+ */
 export function isArray(arg) {
  if (typeof Array.isArray === 'undefined') {
    return Object.prototype.toString.call(arg) === '[object Array]'
--- a/src/views/tab/index.vue
+++ b/src/views/tab/index.vue
@@ -39,7 +39,7 @@ export default {
 </script>

 <style scoped>
-  .tab-container{
+  .tab-container {
    margin: 30px;
  }
 </style>