Merge pull request #3171 from kyletaylored/add-jsdoc-blocks

Add JSDoc blocks to all functions

src/drivers/webextension/js/content.js

@@ -3,6 +3,9 @@
 /* globals chrome */
 
 const Content = {
+  /**
+   * Initialize content detection.
+   */
   async init() {
     await new Promise((resolve) => setTimeout(resolve, 1000))
 
@@ -77,6 +80,10 @@ const Content = {
     }
   },
 
+  /**
+   * Callback for fetching technologies.
+   * @param {Object} technologies
+   */
   onGetTechnologies(technologies) {
     const script = document.createElement('script')
 

src/drivers/webextension/js/driver.js

@@ -16,6 +16,9 @@ const expiry = 1000 * 60 * 60 * 24
 const Driver = {
   lastPing: Date.now(),
 
+  /**
+   * Initialize Chrome extension.
+   */
   async init() {
     chrome.runtime.onConnect.addListener(Driver.onRuntimeConnect)
 
@@ -74,19 +77,38 @@ const Driver = {
     await setOption('version', version)
   },
 
+  /**
+   * Logging utility function.
+   * @param {String} message
+   * @param {String} source
+   * @param {String} type
+   */
   log(message, source = 'driver', type = 'log') {
     // eslint-disable-next-line no-console
     console[type](`wappalyzer | ${source} |`, message)
   },
 
+  /**
+   * Error utility function.
+   * @param {String} error
+   * @param {String} source
+   */
   error(error, source = 'driver') {
     Driver.log(error, source, 'error')
   },
 
+  /**
+   * Open browser tab utility function.
+   * @param {String} url
+   * @param {Boolean} active
+   */
   open(url, active = true) {
     chrome.tabs.create({ url, active })
   },
 
+  /**
+   * Load technologies into memory.
+   */
   async loadTechnologies() {
     try {
       const { apps: technologies, categories } = await (
@@ -100,6 +122,11 @@ const Driver = {
     }
   },
 
+  /**
+   * Post-wrapper for fetch.
+   * @param {String} url
+   * @param {String} body
+   */
   post(url, body) {
     try {
       return fetch(url, {
@@ -111,6 +138,11 @@ const Driver = {
     }
   },
 
+  /**
+   * Analyize JavaScript detections.
+   * @param {String} url
+   * @param {Array} js
+   */
   async analyzeJs(url, js) {
     await Driver.onDetect(
       url,
@@ -127,6 +159,10 @@ const Driver = {
     )
   },
 
+  /**
+   * Initialize PostMessage interface.
+   * @param {Object} port
+   */
   onRuntimeConnect(port) {
     Driver.log(`Connected to ${port.name}`)
 
@@ -150,6 +186,10 @@ const Driver = {
     })
   },
 
+  /**
+   * Callback for WebRequestComplete listener.
+   * @param {Object} request
+   */
   async onWebRequestComplete(request) {
     if (request.responseHeaders) {
       const headers = {}
@@ -183,6 +223,12 @@ const Driver = {
     }
   },
 
+  /**
+   * Callback for onContentLoad listener.
+   * @param {String} url
+   * @param {Object} items
+   * @param {String} language
+   */
   async onContentLoad(url, items, language) {
     try {
       const { hostname } = new URL(url)
@@ -205,10 +251,20 @@ const Driver = {
     }
   },
 
+  /**
+   * Get technology detections.
+   */
   getTechnologies() {
     return Wappalyzer.technologies
   },
 
+  /**
+   * Callback for detections.
+   * @param {String} url
+   * @param {Array} detections
+   * @param {String} language
+   * @param {Boolean} incrementHits
+   */
   async onDetect(url, detections = [], language, incrementHits = false) {
     if (!detections.length) {
       return
@@ -293,12 +349,21 @@ const Driver = {
     await Driver.ping()
   },
 
+  /**
+   * Callback for onAd listener.
+   * @param {Object} ad
+   */
   async onAd(ad) {
     Driver.cache.ads.push(ad)
 
     await setOption('ads', Driver.cache.ads)
   },
 
+  /**
+   * Generate linked icon for detections.
+   * @param {String} url
+   * @param {Object} technologies
+   */
   async setIcon(url, technologies) {
     const dynamicIcon = await getOption('dynamicIcon', true)
 
@@ -334,6 +399,9 @@ const Driver = {
     )
   },
 
+  /**
+   * Get detections from site.
+   */
   async getDetections() {
     const [{ id }] = await promisify(chrome.tabs, 'query', {
       active: true,
@@ -343,6 +411,11 @@ const Driver = {
     return Driver.cache.tabs[id]
   },
 
+  /**
+   * Check for robot rules on site.
+   * @param {String} hostname
+   * @param {Boolean} secure
+   */
   async getRobots(hostname, secure = false) {
     if (!(await getOption('tracking', true))) {
       return
@@ -410,6 +483,10 @@ const Driver = {
     }
   },
 
+  /**
+   * Check for robots.txt rules.
+   * @param {String} href
+   */
   async checkRobots(href) {
     const url = new URL(href)
 
@@ -427,6 +504,9 @@ const Driver = {
     }
   },
 
+  /**
+   * Ping back home.
+   */
   async ping() {
     const tracking = await getOption('tracking', true)
     const termsAccepted =

src/drivers/webextension/js/options.js

@@ -5,6 +5,9 @@
 const { i18n, getOption, setOption } = Utils
 
 const Options = {
+  /**
+   * Initialize Chrome options.
+   */
   async init() {
     // Theme mode
     const themeMode = await getOption('themeMode', false)

src/drivers/webextension/js/popup.js

@@ -7,6 +7,9 @@ const { agent, i18n, getOption, setOption, promisify } = Utils
 const Popup = {
   port: chrome.runtime.connect({ name: 'popup.js' }),
 
+  /**
+   * Initialize popup.
+   */
   async init() {
     // Templates
     Popup.templates = Array.from(
@@ -47,6 +50,7 @@ const Popup = {
         Popup.driver('getDetections')
       })
 
+      // Run internationalization.
       i18n()
     }
 
@@ -67,14 +71,27 @@ const Popup = {
       .addEventListener('click', () => chrome.runtime.openOptionsPage())
   },
 
+  /**
+   * Apply function to postMessage request.
+   * @param {function} func
+   * @param  {...any} args
+   */
   driver(func, ...args) {
     Popup.port.postMessage({ func, args })
   },
 
+  /**
+   * Log message.
+   * @param {String} message
+   */
   log(message) {
     Popup.driver('log', message, 'popup.js')
   },
 
+  /**
+   * Group technologies into categories.
+   * @param {Object} technologies
+   */
   categorise(technologies) {
     return Object.values(
       technologies.reduce((categories, technology) => {
@@ -92,6 +109,10 @@ const Popup = {
     )
   },
 
+  /**
+   * Callback for getDetection listener.
+   * @param {Array} detections
+   */
   async onGetDetections(detections) {
     const pinnedCategory = await getOption('pinnedCategory')
 
@@ -189,6 +210,7 @@ const Popup = {
   }
 }
 
+// Add listener for popup PostMessage API.
 Popup.port.onMessage.addListener(({ func, args }) => {
   const onFunc = `on${func.charAt(0).toUpperCase() + func.slice(1)}`
 

src/drivers/webextension/js/utils.js

@@ -5,6 +5,12 @@
 const Utils = {
   agent: chrome.extension.getURL('/').startsWith('moz-') ? 'firefox' : 'chrome',
 
+  /**
+   * Promise utility tool.
+   * @param {Object} context
+   * @param {String} method
+   * @param  {...any} args
+   */
   promisify(context, method, ...args) {
     return new Promise((resolve, reject) => {
       context[method](...args, (...args) => {
@@ -17,10 +23,20 @@ const Utils = {
     })
   },
 
+  /**
+   * Chrome tab utility.
+   * @param {String} url
+   * @param {Boolean} active
+   */
   open(url, active = true) {
     chrome.tabs.create({ url, active })
   },
 
+  /**
+   * Get value from local storage.
+   * @param {String} name
+   * @param {string|mixed|null} defaultValue
+   */
   async getOption(name, defaultValue = null) {
     try {
       const option = await Utils.promisify(chrome.storage.local, 'get', name)
@@ -35,6 +51,11 @@ const Utils = {
     }
   },
 
+  /**
+   * Set value in local storage.
+   * @param {String} name
+   * @param {String} value
+   */
   async setOption(name, value) {
     try {
       await Utils.promisify(chrome.storage.local, 'set', {
@@ -45,6 +66,9 @@ const Utils = {
     }
   },
 
+  /**
+   * Load internationalization.
+   */
   i18n() {
     Array.from(document.querySelectorAll('[data-i18n]')).forEach(
       (node) => (node.innerHTML = chrome.i18n.getMessage(node.dataset.i18n))

src/wappalyzer.js

@@ -20,6 +20,10 @@ const Wappalyzer = {
     return Wappalyzer.categories.find(({ id: _id }) => id === _id)
   },
 
+  /**
+   * Resolve promises for implied technology.
+   * @param {Array} detections
+   */
   resolve(detections = []) {
     const resolved = detections.reduce((resolved, { technology }) => {
       if (
@@ -75,6 +79,10 @@ const Wappalyzer = {
       )
   },
 
+  /**
+   * Resolve promises for version of technology.
+   * @param {Promise} resolved
+   */
   resolveVersion({ version, regex }, match) {
     let resolved = version
 
@@ -106,6 +114,10 @@ const Wappalyzer = {
     return resolved
   },
 
+  /**
+   * Resolve promises for excluded technology.
+   * @param {Promise} resolved
+   */
   resolveExcludes(resolved) {
     resolved.forEach(({ technology }) => {
       technology.excludes.forEach(({ name }) => {
@@ -124,6 +136,10 @@ const Wappalyzer = {
     })
   },
 
+  /**
+   * Resolve promises for implied technology.
+   * @param {Promise} resolved
+   */
   resolveImplies(resolved) {
     let done = false
 
@@ -156,6 +172,10 @@ const Wappalyzer = {
     }
   },
 
+  /**
+   * Initialize analyzation.
+   * @param {*} param0
+   */
   analyze({ url, html, meta, headers, cookies, scripts }) {
     const oo = Wappalyzer.analyzeOneToOne
     const om = Wappalyzer.analyzeOneToMany
@@ -183,6 +203,10 @@ const Wappalyzer = {
     }
   },
 
+  /**
+   * Extract technologies from data collected.
+   * @param {*object} data
+   */
   setTechnologies(data) {
     const transform = Wappalyzer.transformPatterns
 
@@ -228,6 +252,10 @@ const Wappalyzer = {
     }, [])
   },
 
+  /**
+   * Assign categories for data.
+   * @param {Object} data
+   */
   setCategories(data) {
     Wappalyzer.categories = Object.keys(data)
       .reduce((categories, id) => {
@@ -244,6 +272,10 @@ const Wappalyzer = {
       .sort(({ priority: a }, { priority: b }) => (a > b ? -1 : 0))
   },
 
+  /**
+   * Extract information from regex pattern.
+   * @param {string|array} patterns
+   */
   transformPatterns(patterns) {
     if (!patterns) {
       return []
@@ -291,6 +323,12 @@ const Wappalyzer = {
     return 'main' in parsed ? parsed.main : parsed
   },
 
+  /**
+   * @todo describe
+   * @param {Object} technology
+   * @param {String} type
+   * @param {String} value
+   */
   analyzeOneToOne(technology, type, value) {
     return technology[type].reduce((technologies, pattern) => {
       if (pattern.regex.test(value)) {
@@ -305,6 +343,12 @@ const Wappalyzer = {
     }, [])
   },
 
+  /**
+   * @todo update
+   * @param {Object} technology
+   * @param {String} type
+   * @param {Array} items
+   */
   analyzeOneToMany(technology, type, items = []) {
     return items.reduce((technologies, value) => {
       const patterns = technology[type] || []
@@ -323,6 +367,12 @@ const Wappalyzer = {
     }, [])
   },
 
+  /**
+   *
+   * @param {Object} technology
+   * @param {String} type
+   * @param {Array} items
+   */
   analyzeManyToMany(technology, type, items = {}) {
     return Object.keys(technology[type]).reduce((technologies, key) => {
       const patterns = technology[type][key] || []