language: elaborate docs to show config options (#1622)

packages/language/src/document.js

@@ -30,7 +30,6 @@ var prop = require('propprop');
 /*! Developer Documentation
  *
  * @param {module:language} language - The parent Language object.
- * @param {object=} config - Configuration object.
  */
 /*
  * Create a Natural Language Document object. From this object, you will be able
@@ -39,13 +38,32 @@ var prop = require('propprop');
  * @constructor
  * @alias module:language/document
  *
+ * @param {object|string|module:storage/file} config - Configuration object, the
+ *     inline content of the document, or a Storage File object.
+ * @param {string|module:storage/file} options.content - If using `config` as an
+ *     object to specify the encoding and/or language of the document, use this
+ *     property to pass the inline content of the document or a Storage File
+ *     object.
+ * @param {string} options.encoding - `UTF8`, `UTF16`, or `UTF32`. See
+ *     [`EncodingType`](https://cloud.google.com/natural-language/reference/rest/v1beta1/EncodingType).
+ * @param {string} options.language - The language of the text.
+ * @return {module:language/document}
+ *
  * @example
  * var textToAnalyze = [
  *   'Google is an American multinational technology company specializing in',
  *   'Internet-related services and products.'
  * ].join(' ');
  *
  * var document = language.document(textToAnalyze);
+ *
+ * //-
+ * // Create a Document object with pre-defined configuration, such as its
+ * // language.
+ * //-
+ * var spanishDocument = language.document('¿Dónde está la sede de Google?', {
+ *   language: 'es'
+ * });
  */
 function Document(language, config) {
   var content = config.content || config;
@@ -130,7 +148,8 @@ Document.PART_OF_SPEECH = {
  *
  * @resource [documents.annotateText API Documentation]{@link https://cloud.google.com/natural-language/reference/rest/v1beta1/documents/annotateText}
  *
- * @param {object=} options - Configuration object.
+ * @param {object=} options - Configuration object. See
+ *     [documents.annotateText](https://cloud.google.com/natural-language/reference/rest/v1beta1/documents/annotateText#request-body).
  * @param {boolean} options.entities - Detect the entities from this document.
  *     By default, all features (`entities`, `sentiment`, and `syntax`) are
  *     enabled. By overriding any of these values, all defaults are switched to
@@ -419,7 +438,8 @@ Document.prototype.annotate = function(options, callback) {
  *
  * @resource [documents.analyzeEntities API Documentation]{@link https://cloud.google.com/natural-language/reference/rest/v1beta1/documents/analyzeEntities}
  *
- * @param {object=} options - Configuration object.
+ * @param {object=} options - Configuration object. See
+ *     [documents.annotateText](https://cloud.google.com/natural-language/reference/rest/v1beta1/documents/analyzeEntities#request-body).
  * @param {boolean} options.verbose - Enable verbose mode for more detailed
  *     results. Default: `false`
  * @param {function} callback - The callback function.
@@ -545,7 +565,8 @@ Document.prototype.detectEntities = function(options, callback) {
  *
  * @resource [documents.analyzeSentiment API Documentation]{@link https://cloud.google.com/natural-language/reference/rest/v1beta1/documents/analyzeSentiment}
  *
- * @param {object=} options - Configuration object.
+ * @param {object=} options - Configuration object. See
+ *     [documents.annotateText](https://cloud.google.com/natural-language/reference/rest/v1beta1/documents/analyzeSentiment#request-body).
  * @param {boolean} options.verbose - Enable verbose mode for more detailed
  *     results. Default: `false`
  * @param {function} callback - The callback function.

packages/language/src/index.js

@@ -93,11 +93,12 @@ util.inherits(Language, common.GrpcService);
  * detection, this may be more convenient. However, if you plan to run multiple
  * detections, it's easier to create a {module:language/document} object.
  *
- * @resource [documents.annotate API Documentation]{@link https://cloud.google.com/natural-language/reference/rest/v1beta1/documents/annotate}
+ * @resource [documents.annotate API Documentation]{@link https://cloud.google.com/natural-language/reference/rest/v1beta1/documents/annotateText}
  *
  * @param {string|module:storage/file} content - Inline content or a Storage
  *     File object.
- * @param {object=} options - Configuration object.
+ * @param {object=} options - Configuration object. See
+ *     [documents.annotateText](https://cloud.google.com/natural-language/reference/rest/v1beta1/documents/annotateText#request-body).
  * @param {string} options.encoding - `UTF8`, `UTF16`, or `UTF32`. See
  *     [`EncodingType`](https://cloud.google.com/natural-language/reference/rest/v1beta1/EncodingType).
  * @param {string} options.language - The language of the text.
@@ -136,6 +137,16 @@ util.inherits(Language, common.GrpcService);
  * language.annotate('Hello!', options, callback);
  *
  * //-
+ * // Specify the language the text is written in.
+ * //-
+ * var options = {
+ *   language: 'es',
+ *   entities: true
+ * };
+ *
+ * language.annotate('¿Dónde está la sede de Google?', options, callback);
+ *
+ * //-
  * // Verbose mode may also be enabled for more detailed results.
  * //-
  * var options = {
@@ -170,7 +181,8 @@ Language.prototype.annotate = function(content, options, callback) {
  *
  * @param {string|module:storage/file} content - Inline content or a Storage
  *     File object.
- * @param {object=} options - Configuration object.
+ * @param {object=} options - Configuration object. See
+ *     [documents.annotateText](https://cloud.google.com/natural-language/reference/rest/v1beta1/documents/analyzeEntities#request-body).
  * @param {string} options.encoding - `UTF8`, `UTF16`, or `UTF32`. See
  *     [`EncodingType`](https://cloud.google.com/natural-language/reference/rest/v1beta1/EncodingType).
  * @param {string} options.language - The language of the text.
@@ -209,6 +221,15 @@ Language.prototype.annotate = function(content, options, callback) {
  * language.detectEntities('Axel Foley is from Detroit', options, callback);
  *
  * //-
+ * // Specify the language the text is written in.
+ * //-
+ * var options = {
+ *   language: 'es'
+ * };
+ *
+ * language.detectEntities('Axel Foley es de Detroit', options, callback);
+ *
+ * //-
  * // Verbose mode may also be enabled for more detailed results.
  * //-
  * var options = {
@@ -243,7 +264,8 @@ Language.prototype.detectEntities = function(content, options, callback) {
  *
  * @param {string|module:storage/file} content - Inline content or a Storage
  *     File object.
- * @param {object=} options - Configuration object.
+ * @param {object=} options - Configuration object. See
+ *     [documents.annotateText](https://cloud.google.com/natural-language/reference/rest/v1beta1/documents/analyzeSentiment#request-body).
  * @param {string} options.encoding - `UTF8`, `UTF16`, or `UTF32`. See
  *     [`EncodingType`](https://cloud.google.com/natural-language/reference/rest/v1beta1/EncodingType).
  * @param {string} options.language - The language of the text.
@@ -337,6 +359,14 @@ Language.prototype.detectSentiment = function(content, options, callback) {
  * var document = language.document(file);
  *
  * //-
+ * // Create a Document object with pre-defined configuration, such as its
+ * // language.
+ * //-
+ * var document = language.document('¿Dónde está la sede de Google?', {
+ *   language: 'es'
+ * });
+ *
+ * //-
  * // You can now run detections on the document.
  * //
  * // See {module:language/document} for a complete list of methods available.
@@ -374,6 +404,14 @@ Language.prototype.document = function(config) {
  * var document = language.html(file);
  *
  * //-
+ * // Create a Document object with pre-defined configuration, such as its
+ * // language.
+ * //-
+ * var document = language.html('<h1>Titulo del documento</h1>', {
+ *   language: 'es'
+ * });
+ *
+ * //-
  * // You can now run detections on the document.
  * //
  * // See {module:language/document} for a complete list of methods available.
@@ -416,6 +454,14 @@ Language.prototype.html = function(content, options) {
  * var document = language.text(file);
  *
  * //-
+ * // Create a Document object with pre-defined configuration, such as its
+ * // language.
+ * //-
+ * var document = language.text('¿Dónde está la sede de Google?', {
+ *   language: 'es'
+ * });
+ *
+ * //-
  * // You can now run detections on the document.
  * //
  * // See {module:language/document} for a complete list of methods available.