Update Natural Language docs

Fix error in gcloud authentication.md. [closes #1045]
googleapis · Nov 14, 2016 · 6d28442 · 6d28442
1 parent 8adeef7
commit 6d28442
Show file tree

Hide file tree

Showing 8 changed files with 99 additions and 38 deletions.
diff --git a/README.md b/README.md
@@ -228,7 +228,7 @@ content = "Darth Vader is the best villain in Star Wars."
 document = language.document content
 annotation = document.annotate
 
-annotation.sentiment.polarity #=> 1.0
+annotation.sentiment.score #=> 1.0
 annotation.sentiment.magnitude #=> 0.8999999761581421
 annotation.entities.count #=> 2
 annotation.sentences.count #=> 1

diff --git a/gcloud/README.md b/gcloud/README.md
@@ -15,15 +15,7 @@ $ gem install gcloud
 
 ## Authentication
 
-Unlike other Cloud Platform services, which authenticate using a project
-ID and OAuth 2.0 credentials, Translate API requires a public API access
-key. (This may change in future releases of Translate API.) Follow the
-general instructions at [Identifying your application to
-Google](https://cloud.google.com/translate/v2/using_rest#auth), and the
-specific instructions for [Server
-keys](https://cloud.google.com/translate/v2/using_rest#creating-server-api-keys).
-
-Instructions and configuration options are covered in the [Authentication Guide](https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/google-cloud-translate/guides/authentication).
+Instructions and configuration options are covered in the [Authentication Guide](https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/gcloud/guides/authentication).
 
 ## Example
 

diff --git a/google-cloud-language/README.md b/google-cloud-language/README.md
@@ -31,7 +31,7 @@ content = "Darth Vader is the best villain in Star Wars."
 document = language.document content
 annotation = document.annotate
 
-annotation.sentiment.polarity #=> 1.0
+annotation.sentiment.score #=> 1.0
 annotation.sentiment.magnitude #=> 0.8999999761581421
 annotation.entities.count #=> 2
 annotation.sentences.count #=> 1

diff --git a/google-cloud-language/lib/google/cloud/language.rb b/google-cloud-language/lib/google/cloud/language.rb
@@ -57,8 +57,7 @@ module Cloud
     # (Ruby uses UTF-8 natively, which is the default sent to the API, so unless
     # you're working with text processed in different platform, you should not
     # need to set the encoding type.) Be aware that only English, Spanish, and
-    # Japanese language content are supported, and `sentiment` analysis only
-    # supports English text.
+    # Japanese language content are supported.
     #
     # Use {Language::Project#document} to create documents for the Cloud Natural
     # Language service. You can provide text or HTML content as a string:

diff --git a/google-cloud-language/lib/google/cloud/language/annotation.rb b/google-cloud-language/lib/google/cloud/language/annotation.rb
@@ -186,6 +186,10 @@ def entities
         #   sentiment.magnitude #=> 0.8999999761581421
         #   sentiment.language #=> "en"
         #
+        #   sentence = sentiment.sentences.first
+        #   sentence.sentiment.score #=> 1.0
+        #   sentence.sentiment.magnitude #=> 0.8999999761581421
+        #
         def sentiment
           return nil if @grpc.document_sentiment.nil?
           @sentiment ||= Sentiment.from_grpc @grpc
@@ -273,13 +277,44 @@ def self.from_grpc grpc
         end
 
         ##
-        # TODO: add docs
+        # Provides grammatical information, including morphological information,
+        # about a token, such as the token's tense, person, number, gender,
+        # and so on. Only some of these attributes will be applicable to any
+        # given part of speech. Parts of speech are as defined in [A Universal
+        # Part-of-Speech Tagset]http://www.lrec-conf.org/proceedings/lrec2012/pdf/274_Paper.pdf
+        #
+        # @attr_reader [Symbol] tag The part of speech tag.
+        # @attr_reader [Symbol] aspect The grammatical aspect.
+        # @attr_reader [Symbol] case The grammatical case.
+        # @attr_reader [Symbol] form The grammatical form.
+        # @attr_reader [Symbol] gender The grammatical gender.
+        # @attr_reader [Symbol] mood The grammatical mood.
+        # @attr_reader [Symbol] number The grammatical number.
+        # @attr_reader [Symbol] person The grammatical person.
+        # @attr_reader [Symbol] proper The grammatical properness.
+        # @attr_reader [Symbol] reciprocity The grammatical reciprocity.
+        # @attr_reader [Symbol] tense The grammatical tense.
+        # @attr_reader [Symbol] voice The grammatical voice.
+        #
+        # @example
+        #   require "google/cloud/language"
+        #
+        #   language = Google::Cloud::Language.new
+        #
+        #   content = "Darth Vader is the best villain in Star Wars."
+        #   document = language.document content
+        #   annotation = document.annotate
+        #
+        #   annotation.tokens.count #=> 10
+        #   token = annotation.tokens.first
+        #
+        #   token.text_span.text #=> "Darth"
+        #   token.part_of_speech.tag #=> :NOUN
+        #   token.part_of_speech.gender #=> :MASCULINE
         #
-        # @attr_reader [Symbol] part_of_speech Represents part of speech
-        #   information for a token.
         class PartOfSpeech
-          attr_accessor :tag, :aspect, :case, :form, :gender, :mood, :number,
-                        :person, :proper, :reciprocity, :tense, :voice
+          attr_reader :tag, :aspect, :case, :form, :gender, :mood, :number,
+                      :person, :proper, :reciprocity, :tense, :voice
 
           ##
           # @private Creates a new PartOfSpeech instance.
@@ -397,10 +432,15 @@ def self.from_grpc grpc
           ##
           # Represents the result of sentiment analysis.
           #
-          # @attr_reader [Float] score Score.
-          # @attr_reader [Float] magnitude A non-negative number in the [0,
-          #   +inf] range, which represents the absolute magnitude of sentiment
-          #   regardless of score (positive or negative).
+          # @attr_reader [Float] score The overall emotional leaning of the text
+          #   in the [-1.0, 1.0] range. Larger numbers represent more positive
+          #   sentiments.
+          # @attr_reader [Float] magnitude A non-negative number in the
+          #   [0, +inf] range, which represents the overall strength of emotion
+          #   regardless of score (positive or negative). Unlike score,
+          #   magnitude is not normalized; each expression of emotion within the
+          #   text (both positive and negative) contributes to the text's
+          #   magnitude (so longer text blocks may have greater magnitudes).
           #
           # @example
           #   require "google/cloud/language"
@@ -410,10 +450,15 @@ def self.from_grpc grpc
           #   content = "Darth Vader is the best villain in Star Wars."
           #   document = language.document content
           #   annotation = document.annotate
+          #   sentiment = annotation.sentiment
           #
-          #   sentiment = annotation.sentences.first
           #   sentiment.score #=> 1.0
           #   sentiment.magnitude #=> 0.8999999761581421
+          #   sentiment.language #=> "en"
+          #
+          #   sentence = sentiment.sentences.first
+          #   sentence.sentiment.score #=> 1.0
+          #   sentence.sentiment.magnitude #=> 0.8999999761581421
           #
           class Sentiment
             attr_reader :score, :magnitude
@@ -812,7 +857,14 @@ def wikipedia_url
           end
 
           ##
-          # Returns the `mid` property of the {#metadata}.
+          # Returns the `mid` property of the {#metadata}. The MID
+          # (machine-generated identifier) (MID) correspods to the entity's
+          # [Google Knowledge Graph](https://www.google.com/intl/bn/insidesearch/features/search/knowledge.html)
+          # entry. Note that MID values remain unique across different
+          # languages, so you can use such values to tie entities together from
+          # different languages. For programmatically inspecting these MID
+          # values, please consult the [Google Knowledge Graph Search
+          # API](https://developers.google.com/knowledge-graph/) documentation.
           #
           # @return [String]
           #
@@ -835,7 +887,10 @@ def self.from_grpc grpc
           # Represents a piece of text including relative location.
           #
           # @attr_reader [TextSpan] text_span The entity mention text.
-          # @attr_reader [Symbol] type The type of the entity mention.
+          # @attr_reader [Symbol] type The type of the entity mention. The
+          #   possible return values are `:TYPE_UNKNOWN`, `:PROPER` (proper
+          #   name), and `:COMMON` (Common noun or noun compound).
+          #
           #
           # @example
           #   require "google/cloud/language"
@@ -917,12 +972,15 @@ def self.from_grpc grpc
         ##
         # Represents the result of sentiment analysis.
         #
-        # @attr_reader [Float] score Polarity of the sentiment in the
-        #   [-1.0, 1.0] range. Larger numbers represent more positive
+        # @attr_reader [Float] score The overall emotional leaning of the text
+        #   in the [-1.0, 1.0] range. Larger numbers represent more positive
         #   sentiments.
         # @attr_reader [Float] magnitude A non-negative number in the [0, +inf]
-        #   range, which represents the absolute magnitude of sentiment
-        #   regardless of score (positive or negative).
+        #   range, which represents the overall strength of emotion
+        #   regardless of score (positive or negative). Unlike score, magnitude
+        #   is not normalized; each expression of emotion within the text (both
+        #   positive and negative) contributes to the text's magnitude (so
+        #   longer text blocks may have greater magnitudes).
         # @attr_reader [Array<Sentence>] sentences The sentences returned by
         #   sentiment analysis.
         # @attr_reader [String] language The language of the document (if not

diff --git a/google-cloud-language/lib/google/cloud/language/document.rb b/google-cloud-language/lib/google/cloud/language/document.rb
@@ -29,7 +29,7 @@ module Language
       # should not need to set the encoding type.)
       #
       # Be aware that only English, Spanish, and Japanese language content are
-      # supported, and sentiment analysis only supports English text.
+      # supported.
       #
       # See {Project#document}.
       #
@@ -313,12 +313,18 @@ def entities encoding: nil
         #
         #   language = Google::Cloud::Language.new
         #
-        # content = "Darth Vader is the best villain in Star Wars."
-        # document = language.document content
-        # sentiment = document.sentiment # API call
+        #   content = "Darth Vader is the best villain in Star Wars."
+        #   document = language.document content
+        #
+        #   sentiment = document.sentiment
+        #
+        #   sentiment.score #=> 1.0
+        #   sentiment.magnitude #=> 0.8999999761581421
+        #   sentiment.language #=> "en"
         #
-        # sentiment.score #=> 1.0
-        # sentiment.magnitude #=> 0.8999999761581421
+        #   sentence = sentiment.sentences.first
+        #   sentence.sentiment.score #=> 1.0
+        #   sentence.sentiment.magnitude #=> 0.8999999761581421
         #
         def sentiment encoding: nil
           ensure_service!

diff --git a/google-cloud-language/lib/google/cloud/language/project.rb b/google-cloud-language/lib/google/cloud/language/project.rb
@@ -349,11 +349,18 @@ def entities content, format: :text, language: nil, encoding: nil
         #
         #   language = Google::Cloud::Language.new
         #
-        #   document = language.document "Hello Chris and Mike!"
+        #   content = "Darth Vader is the best villain in Star Wars."
+        #   document = language.document content
         #
         #   sentiment = language.sentiment document
+        #
         #   sentiment.score #=> 1.0
         #   sentiment.magnitude #=> 0.8999999761581421
+        #   sentiment.language #=> "en"
+        #
+        #   sentence = sentiment.sentences.first
+        #   sentence.sentiment.score #=> 1.0
+        #   sentence.sentiment.magnitude #=> 0.8999999761581421
         #
         def sentiment content, format: :text, language: nil, encoding: nil
           ensure_service!

diff --git a/...ud-language/lib/google/cloud/language/v1/doc/google/cloud/language/v1/language_service.rb b/...ud-language/lib/google/cloud/language/v1/doc/google/cloud/language/v1/language_service.rb
@@ -40,8 +40,7 @@ module V1
         #     **Current Language Restrictions:**
         #
         #      * Only English, Spanish, and Japanese textual content
-        #        are supported, with the following additional restriction:
-        #        * +analyzeSentiment+ only supports English text.
+        #        are supported.
         #     If the language (either specified by the caller or automatically detected)
         #     is not supported by the called API method, an +INVALID_ARGUMENT+ error
         #     is returned.