perf: add jsdoc for utils and format some code (#1883)

src/components/Charts/keyboard.vue

@@ -53,8 +53,7 @@ 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(
-        {
+      this.chart.setOption({
         backgroundColor: '#08263a',
         grid: {
           left: '5%',

src/filters/index.js

@@ -1,6 +1,12 @@
 // 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 +14,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 +28,12 @@ export function timeAgo(time) {
   }
 }
 
-/* 数字 格式化*/
+/**
+ * Number formatting
+ * like 10000 => 10k
+ * @param {number} num
+ * @param {number} digits
+ */
 export function numberFormatter(num, digits) {
   const si = [
     { value: 1E18, symbol: 'E' },
@@ -37,6 +51,10 @@ export function numberFormatter(num, digits) {
   return num.toString()
 }
 
+/**
+ * 10000 => "10,000"
+ * @param {number} num
+ */
 export function toThousandFilter(num) {
   return (+num || 0).toString().replace(/^-?\d+/g, m => m.replace(/(?=(?!\b)(\d{3})+$)/g, ','))
 }

src/layout/components/index.js

@@ -1,5 +1,5 @@
+export { default as AppMain } from './AppMain'
 export { default as Navbar } from './Navbar'
+export { default as Settings } from './Settings'
 export { default as Sidebar } from './Sidebar/index.vue'
 export { default as TagsView } from './TagsView/index.vue'
-export { default as AppMain } from './AppMain'
-export { default as Settings } from './Settings'

src/layout/index.vue

@@ -17,19 +17,19 @@
 
 <script>
 import RightPanel from '@/components/RightPanel'
-import { Navbar, Sidebar, AppMain, TagsView, Settings } from './components'
+import { AppMain, Navbar, Settings, Sidebar, TagsView } from './components'
 import ResizeMixin from './mixin/ResizeHandler'
 import { mapState } from 'vuex'
 
 export default {
   name: 'Layout',
   components: {
-    RightPanel,
-    Navbar,
-    Sidebar,
     AppMain,
-    TagsView,
-    Settings
+    Navbar,
+    RightPanel,
+    Settings,
+    Sidebar,
+    TagsView
   },
   mixins: [ResizeMixin],
   computed: {

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,10 @@ 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 +109,7 @@ export function getQueryObject(url) {
 }
 
 /**
- * @param {Sting} input value
+ * @param {string} input value
  * @returns {number} output value
  */
 export function byteLength(str) {
@@ -110,6 +124,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 +138,10 @@ export function cleanArray(actual) {
   return newArray
 }
 
+/**
+ * @param {Object} json
+ * @returns {Array}
+ */
 export function param(json) {
   if (!json) return ''
   return cleanArray(
@@ -130,6 +152,10 @@ export function param(json) {
   ).join('&')
 }
 
+/**
+ * @param {string} url
+ * @returns {Object}
+ */
 export function param2Obj(url) {
   const search = url.split('?')[1]
   if (!search) {
@@ -146,16 +172,23 @@ 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 +206,10 @@ export function objectMerge(target, source) {
   return target
 }
 
+/**
+ * @param {HTMLElement} element
+ * @param {string} className
+ */
 export function toggleClass(element, className) {
   if (!element || !className) {
     return
@@ -189,45 +226,10 @@ export function toggleClass(element, className) {
   element.className = classString
 }
 
-export const pickerOptions = [
-  {
-    text: '今天',
-    onClick(picker) {
-      const end = new Date()
-      const start = new Date(new Date().toDateString())
-      end.setTime(start.getTime())
-      picker.$emit('pick', [start, end])
-    }
-  },
-  {
-    text: '最近一周',
-    onClick(picker) {
-      const end = new Date(new Date().toDateString())
-      const start = new Date()
-      start.setTime(end.getTime() - 3600 * 1000 * 24 * 7)
-      picker.$emit('pick', [start, end])
-    }
-  },
-  {
-    text: '最近一个月',
-    onClick(picker) {
-      const end = new Date(new Date().toDateString())
-      const start = new Date()
-      start.setTime(start.getTime() - 3600 * 1000 * 24 * 30)
-      picker.$emit('pick', [start, end])
-    }
-  },
-  {
-    text: '最近三个月',
-    onClick(picker) {
-      const end = new Date(new Date().toDateString())
-      const start = new Date()
-      start.setTime(start.getTime() - 3600 * 1000 * 24 * 90)
-      picker.$emit('pick', [start, end])
-    }
-  }
-]
-
+/**
+ * @param {string} type
+ * @returns {Date}
+ */
 export function getTime(type) {
   if (type === 'start') {
     return new Date().getTime() - 3600 * 1000 * 24 * 90
@@ -236,6 +238,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 +283,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 +301,47 @@ 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|$)')

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

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

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]'

src/views/components-demo/sticky.vue

@@ -28,7 +28,7 @@
       </el-dropdown>
 
       <div class="time-container">
-        <el-date-picker v-model="time" :picker-options="pickerOptions" type="datetime" format="yyyy-MM-dd HH:mm:ss" placeholder="Release time" />
+        <el-date-picker v-model="time" type="datetime" format="yyyy-MM-dd HH:mm:ss" placeholder="Release time" />
       </div>
 
       <el-button style="margin-left: 10px;" type="success">