1. ngdocs

It is helpful to add comments and annotation in js files. Basically when coding js/css file, we put all the codes and comments together for easily review and updating; before moving to production stage, we split codes and comments into different folders.

• grunt build to generate a ‘dist’ folder to strip comments, and minify js/css files
• grunt-ngdocs extract all the comments/annotation from js files to generate documents.

Yeoman angular project gives a good example to build a project following this standard.

//1. Gruntfile.js
//add the following in initConfig section:
ngdocs: {
  options: {
    dest: 'docs',
    title: 'Project Document',
    scripts: [ 'angular.js' ],
    html5Mode: false
  },
  src: ['/scripts/**/*.js']
}
//and:
grunt.registerTask('project-docs', ['clean', 'ngdocs']);

// then run:
grunt project-docs

‘docs’ directory will generate in current folder. When open docs/index.html the document homepage will display.

2. Markdown plugin

Webstorm plugins - install Markdown for .md file, this makes README.md easily to edit and review.