plugin.js

  1. /**
  2.  * @module plugin
  3.  */
  5. const fs = require('fs')
  6. const path = require('path')
  7. const utils = require('./utils.js')
  9. /* this allows this module to be tested outside of the jsdoc context */
  10. let logger
  11. try {
  12.   logger = require('jsdoc/util/logger')
  13. } catch (e) {
  14.   logger = { info: function () {} } // console.log
  15. }
  17. // The directory from which following examples will be taken
  18. let _examplesDir = ''
  20. // Holds contents of examples file (JSON) for each class or module
  21. let _examples = {}
  23. // used to avoid double file loads -- jsdoc seems to duplicate tags
  24. let previousValue = null
  25. let previousFilename = null
  27. /**
  28.  * Adds example text to '@examples'-tagged doclets.
  29.  * If examples already exist, they are appended to.
  30.  * @param {Object} doclet - the current JSDoc doclet
  31.  */
  32. function newDoclet ({ doclet }) {
  33.   // console.log(JSON.stringify(doclet, null, 2))
  34.   const name = doclet.name
  35.   let examples = (Array.isArray(_examples)) ? _examples : _examples[name]
  36.   examples = examples || _readExamples(name)
  37.   if (!examples) return
  39.   doclet.examples = doclet.examples || [] // ensure doclet has examples list
  40.   // add each example to the doclet's list
  41.   for (const example of examples) {
  42.     const lines = utils.bodyString(example.code)
  43.     if ('expect' in example) { // add the result at the end, if needed
  44.       lines.push('// <= ' + JSON.stringify(example.expect))
  45.     }
  46.     if (lines[0].startsWith('// caption:')) {
  47.       const str = lines[0].replace('// caption:', '').trim()
  48.       lines[0] = '<caption>' + str + '</caption>'
  49.     }
  50.     doclet.examples.push(lines.join('\n'))
  51.   }
  53.   if (Array.isArray(_examples)) _examples = false
  54. }
  56. /**
  57.  * Defines the '@examples' tag, and the action to be taken
  58.  * when the tag is encountered
  59.  * @param {*} dictionary
  60.  */
  61. function defineTags (dictionary) {
  62.   dictionary.defineTag('examples', {
  63.     mustHaveValue: true,
  64.     onTagged: function (doclet, tag) {
  65.       const filename = doclet.meta.filename
  66.       if (filename !== previousFilename) _examplesDir = ''
  67.       previousFilename = filename
  68.       const value = tag.value
  69.       if (value === previousValue) return // avoid double-processing
  70.       previousValue = value
  71.       if (fs.existsSync(value) && fs.lstatSync(value).isDirectory()) {
  72.         logger.info('examples directory:', value)
  73.         _examplesDir = value
  74.         _examples = {} // null
  75.       } else { // read example file
  76.         _readExamples(doclet.name, value)
  77.       }
  78.     }
  79.   })
  80. }
  82. function _readExamples (name, fn) {
  83.   const expath = path.resolve(_examplesDir, fn || name + '.js')
  84.   if (fs.existsSync(expath)) {
  85.     logger.info('Reading @examples: ', expath)
  86.     _examples = utils.examples(expath)
  87.     if (_examples.examples) {
  88.       if (_examples.setup) {
  89.         _examples.examples[name] = [{ code: _examples.setup }]
  90.       }
  91.       _examples = _examples.examples
  92.     }
  93.   }
  94.   return (Array.isArray(_examples)) ? _examples : _examples[name]
  95. }
  97. module.exports = {
  98.   handlers: { newDoclet: newDoclet },
  99.   defineTags: defineTags
  100. }