chore(Predictions) : Add doc comments (#1239)

thisisabhash · web-flow · commit 805792560eaa · 2021-06-17T16:52:13.000-07:00
* chore(Predictions) : Added doc comments

* Add more doc comments in Predictions category

* Update doc comments as per review comments

* Address review comments
diff --git a/Amplify/Categories/Predictions/Models/AgeRange.swift b/Amplify/Categories/Predictions/Models/AgeRange.swift
@@ -7,6 +7,8 @@
 
 import Foundation
 
+/// Age range of an entity(faces/celebrities) detected
+/// as a result of identify() API
 public struct AgeRange {
     public let low: Int
     public let high: Int
diff --git a/Amplify/Categories/Predictions/Models/Attribute.swift b/Amplify/Categories/Predictions/Models/Attribute.swift
@@ -7,6 +7,7 @@
 
 import Foundation
 
+/// Attribute of an entity identified as a result of identify() API
 public struct Attribute {
     public let name: String
     public let value: Bool
@@ -19,6 +20,8 @@ public struct Attribute {
     }
 }
 
+/// Gender of an entity(face/celebrity) identified with
+/// associated confidence value
 public struct GenderAttribute {
     public var gender: GenderType
     public var confidence: Double
diff --git a/Amplify/Categories/Predictions/Models/BoundedKeyValue.swift b/Amplify/Categories/Predictions/Models/BoundedKeyValue.swift
@@ -7,6 +7,9 @@
 
 import CoreGraphics
 
+/// Describes the data extracted as key-value pair in
+/// an image/document resulting from identify() API
+/// e.g The text "Name: John Doe" present in an image/document
 public struct BoundedKeyValue {
     public let key: String
     public let value: String
diff --git a/Amplify/Categories/Predictions/Models/Celebrity.swift b/Amplify/Categories/Predictions/Models/Celebrity.swift
@@ -8,6 +8,9 @@
 import Foundation
 import CoreGraphics
 
+/// Describes a celebrity identified in an image
+/// with information about its location(bounding box) and
+/// facial features(landmarks)
 public struct Celebrity {
     public let metadata: CelebrityMetadata
     public let boundingBox: CGRect
@@ -20,6 +23,7 @@ public struct Celebrity {
     }
 }
 
+/// Celebrity metadata identified as a result of identify() API
 public struct CelebrityMetadata {
     public let name: String
     public let identifier: String
diff --git a/Amplify/Categories/Predictions/Models/Emotion.swift b/Amplify/Categories/Predictions/Models/Emotion.swift
@@ -5,6 +5,9 @@
 // SPDX-License-Identifier: Apache-2.0
 //
 
+/// Emotion identified in an entity(faces/celebrities)
+/// as a result of identify() API with associated `EmotionType`
+/// and confidence value
 public struct Emotion {
     public let emotion: EmotionType
     public let confidence: Double
diff --git a/Amplify/Categories/Predictions/Models/EmotionType.swift b/Amplify/Categories/Predictions/Models/EmotionType.swift
@@ -5,6 +5,8 @@
 // SPDX-License-Identifier: Apache-2.0
 //
 
+/// Different emotion types returned as a result of
+/// identify() API call
 public enum EmotionType {
     case angry
     case calm
diff --git a/Amplify/Categories/Predictions/Models/Entity.swift b/Amplify/Categories/Predictions/Models/Entity.swift
@@ -7,7 +7,8 @@
 
 import CoreGraphics
 
-/// Struct that holds the result of an entity detected from an image per the Identify method
+/// Result returned as part of identify() API call with
+/// `IdentifyAction.detectEntities` type parameter
 public struct Entity {
     public let boundingBox: CGRect
     public let landmarks: [Landmark]
diff --git a/Amplify/Categories/Predictions/Models/EntityDetectionResult.swift b/Amplify/Categories/Predictions/Models/EntityDetectionResult.swift
@@ -5,7 +5,8 @@
 // SPDX-License-Identifier: Apache-2.0
 //
 
-/// Struct that holds the entity detection result for a string of text for the Predictions category
+/// Describes the result of interpret() API when the analyzed text
+/// contains a person/place
 public struct EntityDetectionResult {
     public let type: EntityType
     public let targetText: String
diff --git a/Amplify/Categories/Predictions/Models/EntityMatch.swift b/Amplify/Categories/Predictions/Models/EntityMatch.swift
@@ -7,8 +7,8 @@
 
 import CoreGraphics
 
-/// Struct that holds the result for an entity matched from an entity collection
-/// created on Rekogniton and detected from Predictions Identify methods.
+/// Describes the result for an entity matched in an entity collection
+/// created on AWS Rekogniton and detected from identify() API call
 public struct EntityMatch {
     public let boundingBox: CGRect
     public let metadata: EntityMatchMetadata
diff --git a/Amplify/Categories/Predictions/Models/EntityType.swift b/Amplify/Categories/Predictions/Models/EntityType.swift
@@ -5,6 +5,8 @@
 // SPDX-License-Identifier: Apache-2.0
 //
 
+/// Different entity types detected in a text as a result of
+/// interpret() API
 public enum EntityType: String {
     case commercialItem
     case date
diff --git a/Amplify/Categories/Predictions/Models/GenderType.swift b/Amplify/Categories/Predictions/Models/GenderType.swift
@@ -5,6 +5,8 @@
 // SPDX-License-Identifier: Apache-2.0
 //
 
+/// Describes gender of an entity identified as a result of
+/// identify() API
 public enum GenderType: String {
     case male
     case female
diff --git a/Amplify/Categories/Predictions/Models/IdentifiedLine.swift b/Amplify/Categories/Predictions/Models/IdentifiedLine.swift
@@ -7,6 +7,8 @@
 
 import CoreGraphics
 
+/// Describes a line of text identified in an image as a result of
+/// identify() API call
 public struct IdentifiedLine: IdentifiedText {
 
     public let text: String
diff --git a/Amplify/Categories/Predictions/Models/IdentifiedText.swift b/Amplify/Categories/Predictions/Models/IdentifiedText.swift
@@ -7,6 +7,7 @@
 
 import CoreGraphics
 
+/// protocol describing identified text in an image
 public protocol IdentifiedText {
     var text: String { get }
     var boundingBox: CGRect { get }
diff --git a/Amplify/Categories/Predictions/Models/IdentifiedWord.swift b/Amplify/Categories/Predictions/Models/IdentifiedWord.swift
@@ -7,6 +7,8 @@
 
 import CoreGraphics
 
+/// Describes a word identified in an image as a result of
+/// identify() API call
 public struct IdentifiedWord: IdentifiedText {
     public let text: String
     public let boundingBox: CGRect
diff --git a/Amplify/Categories/Predictions/Models/IdentifyAction.swift b/Amplify/Categories/Predictions/Models/IdentifyAction.swift
@@ -5,6 +5,8 @@
 // SPDX-License-Identifier: Apache-2.0
 //
 
+/// Identification criteria provided to
+/// type parameter in identify() API
 public enum IdentifyAction {
     case detectCelebrity
     case detectLabels(LabelType)
diff --git a/Amplify/Categories/Predictions/Models/KeyPhrase.swift b/Amplify/Categories/Predictions/Models/KeyPhrase.swift
@@ -5,6 +5,8 @@
 // SPDX-License-Identifier: Apache-2.0
 //
 
+/// Describes a key phrase identified in a text as
+/// a result of interpret() API call
 public struct KeyPhrase {
 
     public let score: Float?
diff --git a/Amplify/Categories/Predictions/Models/Landmark.swift b/Amplify/Categories/Predictions/Models/Landmark.swift
@@ -7,6 +7,8 @@
 
 import CoreGraphics
 
+/// Describes the facial feature in a celebrity/entity
+/// identified as a result of identify() API
 public struct Landmark {
     public let type: LandmarkType
     public let points: [CGPoint]
@@ -17,6 +19,7 @@ public struct Landmark {
     }
 }
 
+/// different types of facial features
 public enum LandmarkType {
 
     case allPoints
diff --git a/Amplify/Categories/Predictions/Models/LanguageDetectionResult.swift b/Amplify/Categories/Predictions/Models/LanguageDetectionResult.swift
@@ -5,6 +5,8 @@
 // SPDX-License-Identifier: Apache-2.0
 //
 
+/// Result describing language identified in a text
+/// from interpret() API call
 public struct LanguageDetectionResult {
     public let languageCode: LanguageType
     public let score: Double?
diff --git a/Amplify/Categories/Predictions/Models/PartOfSpeech.swift b/Amplify/Categories/Predictions/Models/PartOfSpeech.swift
@@ -5,6 +5,7 @@
 // SPDX-License-Identifier: Apache-2.0
 //
 
+/// Part of speech identified in a text from interpret() API
 public struct PartOfSpeech {
     public let tag: SpeechType
     public let score: Float?
diff --git a/Amplify/Categories/Predictions/Models/Pose.swift b/Amplify/Categories/Predictions/Models/Pose.swift
@@ -5,6 +5,7 @@
 // SPDX-License-Identifier: Apache-2.0
 //
 
+/// Describes the pose of a person identified in an image from identify() API
 public struct Pose {
     public let pitch: Double
     public let roll: Double
diff --git a/Amplify/Categories/Predictions/Models/SpeechType.swift b/Amplify/Categories/Predictions/Models/SpeechType.swift
@@ -5,6 +5,8 @@
 // SPDX-License-Identifier: Apache-2.0
 //
 
+/// Parts of speech returned
+/// as a result of interpret() API
 public enum SpeechType: String {
     case adjective
     case adposition
diff --git a/Amplify/Categories/Predictions/Models/SyntaxToken.swift b/Amplify/Categories/Predictions/Models/SyntaxToken.swift
@@ -5,6 +5,8 @@
 // SPDX-License-Identifier: Apache-2.0
 //
 
+/// Describes syntactical information resulting from text interpretation as
+/// a result of interpret() API
 public struct SyntaxToken {
 
     public let tokenId: Int
diff --git a/Amplify/Categories/Predictions/Models/TextFormatType.swift b/Amplify/Categories/Predictions/Models/TextFormatType.swift
@@ -5,6 +5,9 @@
 // SPDX-License-Identifier: Apache-2.0
 //
 
+/// Describes different text formats passed a type parameter
+/// to identify().
+
 public enum TextFormatType: String {
     case form
     case table
diff --git a/Amplify/Categories/Predictions/PredictionsCategory+ClientBehavior.swift b/Amplify/Categories/Predictions/PredictionsCategory+ClientBehavior.swift
@@ -9,6 +9,10 @@ import Foundation
 
 extension PredictionsCategory: PredictionsCategoryBehavior {
 
+    /// Synthesize the text to audio
+    /// - Parameter textToSpeech: The text to be synthesized to audio
+    /// - Parameter listener: Triggered when the event occurs
+    /// - Parameter options: Parameters to specific plugin behavior
     @discardableResult
     public func convert(textToSpeech: String,
                         options: PredictionsTextToSpeechRequest.Options? = nil,
@@ -19,6 +23,12 @@ extension PredictionsCategory: PredictionsCategoryBehavior {
                        listener: listener)
     }
 
+    /// Translate the text to the language specified.
+    /// - Parameter textToTranslate: The text to translate
+    /// - Parameter language: The language of the text given
+    /// - Parameter targetLanguage: The language to which the text should be translated
+    /// - Parameter options: Parameters to specific plugin behavior
+    /// - Parameter listener: Triggered when the event occurs
     @discardableResult
     public func convert(textToTranslate: String,
                         language: LanguageType?,
@@ -33,6 +43,10 @@ extension PredictionsCategory: PredictionsCategoryBehavior {
                            listener: listener)
     }
 
+    /// Transcribe audio to text
+    /// - Parameter speechToText: The url of the audio to be transcribed
+    /// - Parameter listener: Triggered when the event occurs
+    /// - Parameter options: Parameters to specific plugin behavior
     @discardableResult
     public func convert(speechToText: URL,
                         options: PredictionsSpeechToTextRequest.Options?,
@@ -41,6 +55,11 @@ extension PredictionsCategory: PredictionsCategoryBehavior {
         plugin.convert(speechToText: speechToText, options: options, listener: listener)
     }
 
+    /// Detect contents of an image based on `IdentifyAction`
+    /// - Parameter type: The type of image detection you want to perform
+    /// - Parameter image: The image you are sending
+    /// - Parameter options: Parameters to specific plugin behavior
+    /// - Parameter listener: Triggered when the event occurs
     @discardableResult
     public func identify(type: IdentifyAction,
                          image: URL,
@@ -53,6 +72,11 @@ extension PredictionsCategory: PredictionsCategoryBehavior {
                         listener: listener)
     }
 
+    /// Interpret the text and return sentiment analysis, entity detection, language detection,
+    /// syntax detection, key phrases detection
+    /// - Parameter text: Text to interpret
+    /// - Parameter options:Parameters to specific plugin behavior
+    /// - Parameter options:Parameters to specific plugin behavior
     @discardableResult
     public func interpret(text: String,
                           options: PredictionsInterpretRequest.Options? = nil,
diff --git a/Amplify/Categories/Predictions/PredictionsCategoryBehavior.swift b/Amplify/Categories/Predictions/PredictionsCategoryBehavior.swift
@@ -23,6 +23,7 @@ public protocol PredictionsCategoryBehavior {
                  options: PredictionsTranslateTextRequest.Options?,
                  listener: PredictionsTranslateTextOperation.ResultListener?) -> PredictionsTranslateTextOperation
 
+    /// Synthesize the text to audio
     /// - Parameter textToSpeech: The text to be synthesized to audio
     /// - Parameter listener: Triggered when the event occurs
     /// - Parameter options: Parameters to specific plugin behavior
@@ -31,6 +32,7 @@ public protocol PredictionsCategoryBehavior {
                  options: PredictionsTextToSpeechRequest.Options?,
                  listener: PredictionsTextToSpeechOperation.ResultListener?) -> PredictionsTextToSpeechOperation
 
+    /// Transcribe audio to text
     /// - Parameter speechToText: The url of the audio to be transcribed
     /// - Parameter listener: Triggered when the event occurs
     /// - Parameter options: Parameters to specific plugin behavior
@@ -39,7 +41,7 @@ public protocol PredictionsCategoryBehavior {
                  options: PredictionsSpeechToTextRequest.Options?,
                  listener: PredictionsSpeechToTextOperation.ResultListener?) -> PredictionsSpeechToTextOperation
 
-    /// Translate the text to the language specified.
+    /// Detect contents of an image based on `IdentifyAction`
     /// - Parameter type: The type of image detection you want to perform
     /// - Parameter image: The image you are sending
     /// - Parameter options: Parameters to specific plugin behavior
diff --git a/Amplify/Categories/Predictions/PredictionsCategoryConfiguration.swift b/Amplify/Categories/Predictions/PredictionsCategoryConfiguration.swift
@@ -10,6 +10,7 @@ import Foundation
 public struct PredictionsCategoryConfiguration: CategoryConfiguration {
     public let plugins: [String: JSONValue]
 
+    /// Initialize `plugins` map
     public init(plugins: [String: JSONValue] = [:]) {
         self.plugins = plugins
     }
diff --git a/Amplify/Categories/Predictions/Result/IdentifyCelebritiesResult.swift b/Amplify/Categories/Predictions/Result/IdentifyCelebritiesResult.swift
@@ -5,7 +5,10 @@
 // SPDX-License-Identifier: Apache-2.0
 //
 
+/// Results are mapped to IdentifyCelebritiesResult when .detectCelebrity in passed in the type: field
+/// in identify() API
 public struct IdentifyCelebritiesResult: IdentifyResult {
+
     public let celebrities: [Celebrity]
 
     public init(celebrities: [Celebrity]) {
diff --git a/Amplify/Categories/Predictions/Result/IdentifyDocumentTextResult.swift b/Amplify/Categories/Predictions/Result/IdentifyDocumentTextResult.swift
@@ -5,6 +5,9 @@
 // SPDX-License-Identifier: Apache-2.0
 //
 
+/// Results are mapped to IdentifyDocumentTextResult when .form, .table
+/// or .all is passed for .detectText in the type: field
+/// in identify() API
 public struct IdentifyDocumentTextResult: IdentifyResult {
 
     public let fullText: String
diff --git a/Amplify/Categories/Predictions/Result/IdentifyEntitiesResult.swift b/Amplify/Categories/Predictions/Result/IdentifyEntitiesResult.swift
@@ -5,7 +5,12 @@
 // SPDX-License-Identifier: Apache-2.0
 //
 
+/// Results are mapped to IdentifyEntitiesResult when .detectEntities is
+/// passed to type: field in identify() API and general entities like facial features, landmarks etc.
+/// are needed to be detected
 public struct IdentifyEntitiesResult: IdentifyResult {
+
+    /// List of 'Entity' as a result of Identify query
     public let entities: [Entity]
 
     public init(entities: [Entity]) {
diff --git a/Amplify/Categories/Predictions/Result/IdentifyEntityMatchesResult.swift b/Amplify/Categories/Predictions/Result/IdentifyEntityMatchesResult.swift
@@ -5,7 +5,12 @@
 // SPDX-License-Identifier: Apache-2.0
 //
 
+/// Results are mapped to IdentifyEntityMatchesResult when .detectEntities is
+/// passed to type: field in identify() API and matches from your Rekognition Collection
+/// need to be identified
 public struct IdentifyEntityMatchesResult: IdentifyResult {
+
+    /// List of matched `EntityMatch`
     public let entities: [EntityMatch]
 
     public init(entities: [EntityMatch]) {
diff --git a/Amplify/Categories/Predictions/Result/IdentifyLabelsResult.swift b/Amplify/Categories/Predictions/Result/IdentifyLabelsResult.swift
@@ -7,6 +7,8 @@
 
 import CoreGraphics
 
+/// Results are mapped to IdentifyLabelsResult when .labels in passed to .detectLabels
+/// in the type: field in identify() API
 public struct IdentifyLabelsResult: IdentifyResult {
     public let labels: [Label]
     public let unsafeContent: Bool?
@@ -17,6 +19,7 @@ public struct IdentifyLabelsResult: IdentifyResult {
     }
 }
 
+/// Describes a real world object (e.g., chair, desk) identified in an image
 public struct Label {
     public let name: String
     public let metadata: LabelMetadata?
diff --git a/Amplify/Categories/Predictions/Result/IdentifyTextResult.swift b/Amplify/Categories/Predictions/Result/IdentifyTextResult.swift
diff --git a/Amplify/Categories/Predictions/Result/InterpretResult.swift b/Amplify/Categories/Predictions/Result/InterpretResult.swift
diff --git a/Amplify/Categories/Predictions/Result/SpeechToTextResult.swift b/Amplify/Categories/Predictions/Result/SpeechToTextResult.swift
diff --git a/Amplify/Categories/Predictions/Result/TextToSpeechResult.swift b/Amplify/Categories/Predictions/Result/TextToSpeechResult.swift
diff --git a/Amplify/Categories/Predictions/Result/TranslateTextResult.swift b/Amplify/Categories/Predictions/Result/TranslateTextResult.swift

Original file line number	Diff line number	Diff line change
`@@ -7,6 +7,7 @@`
`7`	`7`
`8`	`8`	`import Foundation`
`9`	`9`
	`10`	`+/// Attribute of an entity identified as a result of identify() API`
`10`	`11`	`public struct Attribute {`
`11`	`12`	`public let name: String`
`12`	`13`	`public let value: Bool`
`@@ -19,6 +20,8 @@ public struct Attribute {`
`19`	`20`	`}`
`20`	`21`	`}`
`21`	`22`
	`23`	`+/// Gender of an entity(face/celebrity) identified with`
	`24`	`+/// associated confidence value`
`22`	`25`	`public struct GenderAttribute {`
`23`	`26`	`public var gender: GenderType`
`24`	`27`	`public var confidence: Double`