Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

Talk at FullStack 2016: Automating documentation on JavaScript projects

516 views

Published on

Documenting code is an important task that few teams get right. Docs get easily outdated, everybody hates writing them and sometimes developers don’t even use them at all.

In this talk, you will learn about an approach to documentation writing based on adding comments directly to the source code. I will also show you its benefits applied to three different types of codebases.

You will also learn how to generate documentation from those same comments in two different flavors as well as when each of them work best.

Published in: Software
  • Be the first to like this

Talk at FullStack 2016: Automating documentation on JavaScript projects

  1. 1. Automating documentation on JavaScript projects Marcos Iglesias @golodhros
  2. 2. My Story
  3. 3. JavaScripTown
  4. 4. Three kinds of code
  5. 5. The Good New and shiny Clean and simple Fully tested
  6. 6. The Bad Entangled old code No documentation or comments Incomplete test suite
  7. 7. The Ugly Complex structure Steep learning curve Fully tested No documentation
  8. 8. Different challenges
  9. 9. The Challenges Goal of open-sourcing it Clear and simple Well documented
  10. 10. The Challenges Easy to get lost in the code Non-obvious relations High level of indirection
  11. 11. The Challenges Unfamiliar conceptual elements New ways of doing things High level of indirection
  12. 12. Documenting JavaScript?
  13. 13. JS documentation is broken
  14. 14. Out of Date
  15. 15. Boring to write
  16. 16. Inconvenient
  17. 17. Comments on the source
  18. 18. Code reviews
  19. 19. Next Up JSDoc comments DocStrap Docco Choosing Benefits
  20. 20. Introducing JSDoc
  21. 21. JSDoc is an API documentation generator for JavaScript
  22. 22. How does it work? Add documentation comments JSDoc tool will scan code and Generate an HTML documentation website
  23. 23. JSDoc API
  24. 24. Functions
  25. 25. @param @param { String } name description
  26. 26. @param @param { (String | Number) } name description
  27. 27. @param @param { String[] } name description
  28. 28. @return @return {[type]} description
  29. 29. @private/public @private or @public
  30. 30. @deprecated
  31. 31. @link @link {[url] | Link text}
  32. 32. JSDoc Example
  33. 33. JSDoc Example
  34. 34. Modules
  35. 35. @file Describes a file
  36. 36. @module Marks file as a module
  37. 37. @requires Dependencies
  38. 38. @version
  39. 39. @example
  40. 40. @tutorial
  41. 41. @typedef
  42. 42. JSDoc editor Extensions
  43. 43. My Story, continued (Improvements with JSDoc)
  44. 44. The Good Favored small and specific methods Became another review of the code Helped state which methods were public or private
  45. 45. The Bad Made clear which methods didn’t belong to each module Stated the dependencies and links between objects Avoided re-reading methods
  46. 46. The Ugly Made it easier to understand the big picture Helped next developers to understand it Avoided re-reading of complex pieces
  47. 47. Generating Documentation
  48. 48. DocStrap
  49. 49. DocStrap is a Bootstrap based template for JSDoc
  50. 50. Generating Docs - DocStrap 1. Install grunt-jsdoc or gulp-jsdoc3 2. Configure JSDoc tasks 3. Install Docstrap 4. Edit config.json 5. Run task 6. (Debug)
  51. 51. Docco
  52. 52. Docco is a vertical layout documentation generator with “prose” and code
  53. 53. Docco comments
  54. 54. //
  55. 55. // comment
  56. 56. Generating Docs - Docco 1. Install Docco as npm package 2. Configure Docco grunt task 3. Add comments for the “Prose” side with // 4. Run grunt task
  57. 57. Which one should you use?
  58. 58. DocStrap Complex pieces of code Is a flow-based program Explain decisions on your code Docco API References Tutorials and Demos Customization
  59. 59. Other options
  60. 60. My Story’s End
  61. 61. The Good JSDoc and Docstrap Complete customization Proud of our project!
  62. 62. The Bad Didn’t want to document it on detail Ask: How you would I like to learn it?
  63. 63. The Ugly JSDoc comments were useful Docco looks like a great candidate
  64. 64. Benefits
  65. 65. Improves communication about the code
  66. 66. Helps understanding other’s code
  67. 67. Generates documentation
  68. 68. Doesn’t get out of date
  69. 69. It’s easy!
  70. 70. Convenient
  71. 71. JSDoc - Resources API Reference Use JSDoc: Index Articles Dr. Axel Rauschmayer - JSDoc intro Tom Macwright - In defense of JSDoc Kaustav Das Modak - JSDoc vs YUIDoc vs Doxx vs Docco Tricks and Best Practices Common Pitfalls in JSDoc DocumentationJS docs
  72. 72. Docco - Resources Reference Docco webpage Articles Derick Bailey - Annotated Source Code As Documentation, With Docco Kaustav Das Modak - JSDoc vs YUIDoc vs Doxx vs Docco
  73. 73. Give it a try!
  74. 74. Thanks for Listening!
  75. 75. Q&A @golodhros
  76. 76. Credits Imagery The Good, The Bad and The Ugly Art by Kwad-rat Sublime Text logo by examinedLiving Atom Icon by adhmadseleem Emacs Icon by cg433n ESLint Icon by Ömer Balyalı

×