removing reference to old use_vcap_services option, improving jsdoc

.gitignore

@@ -1,5 +1,6 @@
 node_modules
 npm-debug.log
+npm-debug.log.*
 coverage
 .DS_Store
 test/resources/auth.js

lib/base_service.js

@@ -24,9 +24,15 @@ var request      = require('request');
 
 
 /**
- * Base class that other services inherit from
+ * Internal base class that other services inherit from
+ * @param {Object} options
+ * @param {String} [options.username] - required unless use_unauthenticated is set
+ * @param {String} [options.password] - required unless use_unauthenticated is set
+ * @param {Boolean} [options.use_unauthenticated] - skip credential requirement
+ * @param {Object} [options.headers]
+ * @param {Boolean} [options.headers.X-Watson-Learning-Opt-Out=false] - opt-out of data collection
+ * @param {String} [options.url] - override default service base url
  * @private
- * @param {Object} [options]
  * @constructor
  */
 function BaseService(user_options) {
@@ -38,15 +44,19 @@ function BaseService(user_options) {
 
   options = this.initCredentials(options);
 
-  options = omit(options, ['version', 'username', 'password',
-    'use_vcap_services', 'use_unauthenticated', 'apikey']);
+  options = omit(options, ['version', 'username', 'password', 'use_unauthenticated', 'apikey']);
 
   if (options.url)
     options.url = helper.stripTrailingSlash(options.url);
 
   this._options = extend({qs: {}, url: this.constructor.URL}, this.serviceDefaults, options);
 }
 
+/**
+ * @private
+ * @param options
+ * @returns {*}
+ */
 BaseService.prototype.initCredentials = function(options) {
   if (options.token) {
     options.headers = options.headers || {};
@@ -92,6 +102,7 @@ BaseService.prototype.initCredentials = function(options) {
  *
  * For example, if service.name is speech_to_text, env properties are SPEECH_TO_TEXT_USERNAME and SPEECH_TO_TEXT_PASSWORD
  *
+ * @private
  * @param name
  * @returns {{username: String|undefined, password: String|undefined}}
  */

text-to-speech/v1.js

@@ -23,6 +23,7 @@ var util = require('util');
 var BaseService = require('../lib/base_service');
 
 /**
+ * Watson Text to Speech service
  *
  * @param options
  * @constructor