{"id":45245,"date":"2016-02-29T08:00:04","date_gmt":"2016-02-29T16:00:04","guid":{"rendered":"https:\/\/redfindevelop.wpengine.com\/blog\/?p=45245"},"modified":"2020-10-05T13:11:59","modified_gmt":"2020-10-05T20:11:59","slug":"javascript-documentation-generator-showdown","status":"publish","type":"post","link":"https:\/\/www.redfin.com\/news\/javascript-documentation-generator-showdown\/","title":{"rendered":"JavaScript Documentation Generator Showdown"},"content":{"rendered":"

Redfin has been working on making it easier to share common ui components between the different sites we own, and we need<\/span> documentation available that makes it easy for new developers to use and contribute. Documentation generators parse existing source code for comments and create documents that can be used for reference. These documents are then used by developers to contribute to development, and to understand how to use the api. To produce the best docs for contributors, we did some serious considering and eventually found the winners.<\/span><\/p>\n

Evaluation Criteria<\/b><\/h3>\n

Requirements<\/b><\/h4>\n
    \n
  1. An un-opinionated doc framework: as our common components are fairly mature, we cannot be involved in a major code refactor to appease a documentation framework.<\/span><\/li>\n
  2. Links and references to tutorials that are maintained independent of code: many kinds of documentation belong in the code — params, return values — but many don’t, such as tutorials. We want them to be tightly coupled, but stored independently.<\/span><\/li>\n
  3. Links back to the source code: to encourage developers to not only use, but also contribute, it should be easy for developers to go from browsing the documentation to browsing the code from which it was generated, ideally on GitHub.<\/span><\/li>\n
  4. Graceful handling of ES6 and ES7 features, as well as jsx.<\/span><\/li>\n<\/ol>\n

    Nice to Have<\/b><\/h4>\n
      \n
    1. Documentation coverage: you can’t improve what you don’t measure.<\/span><\/li>\n
    2. Customizable output format: it would be nice to have Redfin-styled docs.<\/span><\/li>\n
    3. Searchable docs: who even browses anymore?<\/span><\/li>\n
    4. Todo flagging: it will help recruit developers from feature teams to contribute to the project if there is an explicit list of things for them to do.<\/span><\/li>\n<\/ol>\n

      Structured vs Unstructured<\/b><\/h3>\n

      Ideally, we’d like to auto-generate docs from the comments that already exist in the code base with minimal changes. The developers who have come before have done a good job documenting the existing code; using a doc tool should not require rewriting all of our comments. However, to facilitate searchability, documentation coverage, and well-documented contributions in the future, structured comments may actually be better in the long run.<\/span><\/p>\n

      What We Considered<\/b><\/h3>\n

      ESDoc<\/b><\/h3>\n

      Example<\/b><\/h4>\n