How to use JSDoc

Instalation

JSDoc is part of our dependencies so it should already be installed if you ran npm install from the server folder. You can also install it globally by running npm install jsdoc -g

Go to http://usejsdoc.org/ for more information

Setup/Configuration

Create a folder called /documentation and create a configuration file conf.json

Inside conf.json you need to define all the files that JSDoc needs to run through and document. It should like something like this:

      {
        "tags": {
          "allowUnknownTags": true,
          "dictionaries": ["jsdoc","closure"]
        },
        "source":{
          "include":[ 
            "docInit.js",
            "../client/scripts/app.js",
            "../client/scripts/controllers/chatterbox.js",
            "../client/scripts/controllers/initializeMap.js",
            "../client/scripts/controllers/registerLoginLogout.js",
            "../client/scripts/controllers/watchCurrentLocation.js",
            "../client/scripts/services/config.js",
            "../client/scripts/services/customDirectives.js",
            "../client/scripts/services/factoryDatabaseAndAuth.js",
            "../client/scripts/services/factoryRunListeners.js"
          ],
          "exclude":["client/styles/style.css"],
          "includePattern": ".+\\.js(doc)?$",
          "excludePattern": "(^|\\/|\\\\)_"
        },
        "plugins": [],
        "templates": {
            "cleverLinks": false,
            "monospaceLinks": false
        }
      }

You'll just have to change file locations and names to make it applicable to your app

Comments

JSDoc uses comments above your functions to create documentation. Comments need to be in a particular format. We opted for a simple approach (you'll find our comments in every script file). For example:

      /**
        * @class watchCurrentUserLocation
        * @description Controller for geolocation. Monitors user's location. Uses browser built-in method
        * 'navigator.geolocation.watchPosition' that triggers every time there is a change in user's 
        * location (triggered when $rootScope broadcasts that user is currently logged in). 
      */

      /**
        * @function success
        * @memberOf watchCurrentUserLocation
        * @description Triggers when change in user location is detected. Sends the user's location to 
        * the database (based on the user's unique ID)
      */

@class - your function name. This gives your function a separate html page and a link in the sidebar/navbar
@description - describe your function
@function - name your function
@memberOf - this function is subordinate of watchCurrentUserLocation (so it lives on the same page as watchCurrentUserLocation)

Both examples come from watchCurrentUserLocation.js file, so check it out for more information

Running JSDoc

After you set up your conf.json and you comment all your desired files, now you run JSDoc with the following command:

jsdoc -c conf.json

This command will execute the conf.json file and all the files listed inside it. Your documentation will be in a folder called "out" located in the same folder where conf.json is located.

At this point you just hvae to find index.html inside folder "out" and open it up. Your documentation is ready!

The last step is to add content to the home page and modify any page(s) according to your needs