解决jsdoc生成文档的导航条中不显示类实例属性的问题

用 jsdoc 来生成 js 文档，默认情况下导航条中是只显示类名和实例方法名，对于实例属性是不显示的。实际工作中文档使用起来总感觉很不方便。这里结合 jsdoc 模板主题做一点简单的修改来解决这个问题。

jsDoc的官方推荐了7种模板

• jaguarjs-jsdoc
• DocStrap
• jsdoc3Template
• minami
• docdash
• tui-jsdoc-template
• better-docs

比较了一下还是觉得 docdash 模板看着顺眼，所以本文针对 docdash 模板做修改。

版本

• jsdoc 4.0.0
• docdash 2.0.1

jsdoc.conf.js

{
  "plugins": [],
  "recurseDepth": 10,
  "source": {
    "include": [
      "js/board.js"
    ],
    "includePattern": ".+\\.js(doc|x)?$",
    "excludePattern": "(^|\\/|\\\\)_"
  },
  "sourceType": "module",
  "tags": {
    "allowUnknownTags": true,
    "dictionaries": [
      "jsdoc"
    ]
  },
  "templates": {
    "cleverLinks": false,
    "monospaceLinks": false
  },
  "opts": {
    "template": "node_modules/docdash"
  },
  "docdash": {
    "search": true,    //开启搜索
    "collapse": true,  //开启折叠
    "sort":false,      //不排序
    "static":true      //显示静态成员，本文的修改借用了此开关
  }
}

修改node_modules/docdash/publish.js

我们主要需要修改的是 docdash 的 publish.js文件

//利用static开关，在这一行将实例属性加进去
if (docdash.static && members.find(function (m) { return (m.scope === 'static'||m.scope==='instance'); } )) {
  itemsNav += "<ul class='members'>";

  //加一个└ Members标题
  if(docdash.collapse)
  itemsNav+="<li style='font-weight:bold;font-size:12px;display:none'>└ Members</li>"
  else
  itemsNav+="<li style='font-weight:bold;font-size:12px;'>└ Members</li>"

  members.forEach(function (member) {
      //屏蔽这一行
      // if (!member.scope === 'static') return;
      itemsNav += "<li data-type='member'";
      if(docdash.collapse)
          itemsNav += " style='display: none;'";
      itemsNav += ">";
      //区分静态属性和实例属性，并给静态属性加一个[static]标记
      if(member.scope==='static'){
          itemsNav += linkto(member.longname, '[static] '+member.name);
      }else{
          itemsNav += linkto(member.longname, member.name);
      }
      
      itemsNav += "</li>";
  });

  itemsNav += "</ul>";
}

if (methods.length) {
  itemsNav += "<ul class='methods'>";

  //给方法成员也加一个标题
  if(docdash.collapse)
  itemsNav+="<li style='font-weight:bold;font-size:12px;display:none'>└ Methods</li>"
  else
  itemsNav+="<li style='font-weight:bold;font-size:12px;'>└ Methods</li>"

  methods.forEach(function (method) {
      if (docdash.static === false && method.scope === 'static') return;
      if (docdash.private === false && method.access === 'private') return;
      var navItem = '';
      var navItemLink
      
      //区分一下静态方法和实例方法
      if(method.scope==='static'){
          navItemLink=linkto(method.longname, '[static] '+method.name);
      }else{
          navItemLink=linkto(method.longname, method.name);
      }

      navItem += "<li data-type='method'";
      if(docdash.collapse)
          navItem += " style='display: none;'";
      navItem += ">";
      navItem += navItemLink;
      navItem += "</li>";

      itemsNav += navItem;
  });

  itemsNav += "</ul>";
}

看看改造后的效果