basic doc generation - stil has a few kinks to work out

Author: nfriedly

.gitignore

@@ -6,3 +6,4 @@ test/resources/auth.js
 test/integration/
 test/resources/tts-output.ogg
 .idea
+doc/

.jsdoc.json

@@ -0,0 +1,10 @@
+{
+  "source": {
+    "include": [ "lib/", "services/" ]
+  },
+  "opts": {
+    "package": "package.json",
+    "recurse": true,
+    "destination": "./doc/"
+  }
+}

.npmignore

@@ -12,3 +12,4 @@ examples
 LICENSE
 CONTRIBUTING.md
 RELEASE.md
+.jsdoc.json

lib/index.js

@@ -29,6 +29,11 @@ function encodeBase64(creds) {
   return new Buffer(creds.username + ':' + creds.password).toString('base64');
 }
 
+/**
+ * @private
+ * @param serviceName
+ * @returns {Function}
+ */
 function createServiceAPI(serviceName) {
   return function(user_options) {
     var options = extend({}, user_options);
@@ -128,37 +133,170 @@ function createServiceAPI(serviceName) {
   };
 }
 
-var watson = {};
-
-[
-  'concept_expansion',
-  'question_and_answer',
-  'relationship_extraction',
-  'visual_recognition',
-  'speech_to_text',
-  'text_to_speech',
-  'concept_insights',
-  'tradeoff_analytics',
-  'personality_insights',
-  'natural_language_classifier',
-  'authorization',
-  'language_translation',
-  'tone_analyzer',
-  'dialog',
-  'retrieve_and_rank',
-  'document_conversion',
-  'visual_insights',
+/**
+ * @namespace
+ */
+var watson = {
+
+  /**
+   * @function
+   * @param {{}} options
+   * @returns  {ConceptExpansion}
+   */
+  concept_expansion: createServiceApi('concept_expansion'),
+
+  /**
+   * @function
+   * @param {{}} options
+   * @returns  {QuestionAndAnswer}
+   */
+  question_and_answer: createServiceApi('question_and_answer'),
+
+  /**
+   * @function
+   * @param {{}} options
+   * @returns  {RelationshipExtraction}
+   */
+  relationship_extraction: createServiceApi('relationship_extraction'),
+
+  /**
+   * @function
+   * @param {{}} options
+   * @returns  {VisualRecognitionV1Beta|VisualRecognitionV2Beta}
+   */
+  visual_recognition: createServiceApi('visual_recognition'),
+
+  /**
+   * @function
+   * @param {{}} options
+   * @returns  {SpeechToText}
+   */
+  speech_to_text: createServiceApi('speech_to_text'),
+
+  /**
+   * @function
+   * @param {{}} options
+   * @returns  {TextToSpeech}
+   */
+  text_to_speech: createServiceApi('text_to_speech'),
+
+  /**
+   * @function
+   * @param {{}} options
+   * @returns  {ConceptInsights}
+   */
+  concept_insights: createServiceApi('concept_insights'),
+
+  /**
+   * @function
+   * @param {{}} options
+   * @returns  {TradeoffAnalytics}
+   */
+  tradeoff_analytics: createServiceApi('tradeoff_analytics'),
+
+  /**
+   * @function
+   * @param {{}} options
+   * @returns  {PersonalityInsights}
+   */
+  personality_insights: createServiceApi('personality_insights'),
+
+  /**
+   * @function
+   * @param {{}} options
+   * @returns  {NaturalLanguageClassifier}
+   */
+  natural_language_classifier: createServiceApi('natural_language_classifier'),
+
+  /**
+   * @function
+   * @param {{}} options
+   * @returns  {Authorization}
+   */
+  authorization: createServiceApi('authorization'),
+
+  /**
+   * @function
+   * @param {{}} options
+   * @returns  {LanguageTranslation}
+   */
+  language_translation: createServiceApi('language_translation'),
+
+  /**
+   * @function
+   * @param {{}} options
+   * @returns  {ToneAnalyzer}
+   */
+  tone_analyzer: createServiceApi('tone_analyzer'),
+
+  /**
+   * @function
+   * @param {{}} options
+   * @returns  {Dialog}
+   */
+  dialog: createServiceApi('dialog'),
+
+  /**
+   * @function
+   * @param {{}} options
+   * @returns  {RetrieveAndRank}
+   */
+  retrieve_and_rank: createServiceApi('retrieve_and_rank'),
+
+  /**
+   * @function
+   * @param {{}} options
+   * @returns  {DocumentConversion}
+   */
+  document_conversion: createServiceApi('document_conversion'),
+
+  /**
+   * @function
+   * @param {{}} options
+   * @returns  {VisualInsights}
+   */
+  visual_insights: createServiceApi('visual_insights'),
+
   // deprecated
-  'search',
-  'message_resonance',
+  /**
+   * @function
+   * @param {{}} options
+   * @returns  {Search}
+   * @deprecated Replaced by {@link RetrieveAndRank}
+   */
+  search: createServiceApi('search'),
+
+  /**
+   * @function
+   * @param {{}} options
+   * @returns  {MessageResonance}
+   * @deprecated
+   */
+  message_resonance: createServiceApi('message_resonance'),
 
   // alchemy
-  'alchemy_language',
-  'alchemy_vision',
-  'alchemy_data_news'
+  /**
+   * @function
+   * @param {{}} options
+   * @returns  {AlchemyLanguage}
+   */
+  alchemy_language: createServiceApi('alchemy_language'),
+
+  /**
+   * @function
+   * @param {{}} options
+   * @returns  {AlchemyVision}
+   */
+  alchemy_vision: createServiceApi('alchemy_vision'),
+
+  /**
+   * @function
+   * @param {{}} options
+   * @returns  {AlchemyDataNews}
+   */
+  alchemy_data_news: createServiceApi('alchemy_data_news')
+};
+
 
-].forEach(function(api) {
-  watson[api] = createServiceAPI(api);
-});
 
 module.exports = watson;

lib/requestwrapper.js

@@ -37,6 +37,7 @@ function parsePath(path, params) {
 /**
  * Check if the service/request have error and try to format them.
  * @param  {Function} cb the request callback
+ * @private
  */
 function formatErrorIfExists(cb) {
   return function(error, response, body) {
@@ -74,6 +75,7 @@ function formatErrorIfExists(cb) {
  * 2. Checks for missing parameters
  * 3. Encode path and query parameters
  * 4. Call the api
+ * @private
  */
 function createRequest(parameters, callback) {
   var missingParams = null,

package.json

@@ -61,6 +61,7 @@
     "concat-stream": "^1.5.0",
     "coveralls": "^2.11.4",
     "istanbul": "^0.4.0",
+    "jsdoc": "^3.4.0",
     "jshint": "^2.8.0",
     "mocha": "^2.3.4",
     "nock": "^3.4.0",
@@ -86,6 +87,8 @@
   "scripts": {
     "test": "jshint --exclude ./node_modules/ && mocha --reporter spec --timeout 4000",
     "prepare": "npm test && npm version patch",
+    "doc": "jsdoc -c .jsdoc.json",
+    "watch-doc": "nodemon --watch lib/ --watch services/ --watch .jsdoc.json --watch package.json --exec npm run doc",
     "coverage": "istanbul cover ./node_modules/mocha/bin/_mocha --reporter spec --timeout 4000",
     "coveralls": "istanbul cover ./node_modules/mocha/bin/_mocha --report lcovonly -- -R spec && cat ./coverage/lcov.info | ./node_modules/coveralls/bin/coveralls.js && rm -rf ./coverage"
   }

services/alchemy_data_news/v1.js

@@ -36,6 +36,10 @@ function errorFormatter(cb) {
   };
 }
 
+/**
+ * @param options
+ * @constructor
+ */
 function AlchemyDataNews(options) {
   // Default URL
   var serviceDefaults = {
@@ -48,6 +52,10 @@ function AlchemyDataNews(options) {
 /**
  * Extracts a grouped, ranked list of named entities (people, companies,
  * organizations, etc.) from text, a URL or HTML.
+ * @param {Object} params
+ * @param params.end
+ * @param params.start
+ * @param {Function} callback
  */
 AlchemyDataNews.prototype.getNews = function(params, callback ) {
     params = params || {};

services/alchemy_language/v1.js

@@ -65,6 +65,11 @@ function createRequest(method) {
   };
 }
 
+/**
+ *
+ * @param options
+ * @constructor
+ */
 function AlchemyLanguage(options) {
   // Default URL
   var serviceDefaults = {

services/alchemy_vision/v1.js

@@ -84,6 +84,11 @@ function createRequest(method) {
   };
 }
 
+/**
+ * 
+ * @param options
+ * @constructor
+ */
 function AlchemyVision(options) {
   // Default URL
   var serviceDefaults = {

services/authorization/v1.js

@@ -20,6 +20,11 @@ var extend         = require('extend');
 var requestFactory = require('../../lib/requestwrapper');
 var url            = require('url');
 
+/**
+ *
+ * @param options
+ * @constructor
+ */
 function Authorization(options) {
   // Default URL
   var serviceDefaults = {

services/concept_expansion/v1-beta.js

@@ -74,6 +74,11 @@ function responseFormatter(cb) {
   };
 }
 
+/**
+ *
+ * @param options
+ * @constructor
+ */
 function ConceptExpansion(options) {
   var serviceDefaults = {
     url: 'https://gateway.watsonplatform.net/concept-expansion-beta/api'
@@ -161,4 +166,4 @@ ConceptExpansion.prototype.expand = function(params, callback) {
   });
 };
 
-module.exports = ConceptExpansion;
+module.exports = ConceptExpansion;

services/concept_insights/v2.js

@@ -22,8 +22,9 @@ var requestFactory = require('../../lib/requestwrapper');
 
 /**
  * Format the ids into a JSON array if is a string array
- * @param  {Array or string} ids the concept identifiers
+ * @param  {Array|String} ids the concept identifiers
  * @return {String}     The concept ids as JSON array
+ * @private
  */
 function formatConceptIds(ids) {
   // Initially, we expected the user to supply JSON.stringify'd ids.
@@ -46,6 +47,11 @@ function formatConceptIds(ids) {
   return JSON.stringify(ids);
 }
 
+/**
+ *
+ * @param options
+ * @constructor
+ */
 function ConceptInsights(options) {
   // Default URL
   var serviceDefaults = {