[ai-text-analytics] Various documentation-related changes

sdk/textanalytics/ai-text-analytics/src/analyzeSentimentResultArray.ts

@@ -5,7 +5,7 @@ import {
   TextDocumentBatchStatistics,
   DocumentError,
   DocumentSentiment,
-  MultiLanguageInput
+  TextDocumentInput
 } from "./generated/models";
 import {
   AnalyzeSentimentResult,
@@ -33,7 +33,7 @@ export interface AnalyzeSentimentResultArray extends Array<AnalyzeSentimentResul
 }
 
 export function makeAnalyzeSentimentResultArray(
-  input: MultiLanguageInput[],
+  input: TextDocumentInput[],
   documents: DocumentSentiment[],
   errors: DocumentError[],
   modelVersion: string,

sdk/textanalytics/ai-text-analytics/src/detectLanguageResultArray.ts

@@ -5,7 +5,7 @@ import {
   TextDocumentBatchStatistics,
   DocumentLanguage,
   DocumentError,
-  LanguageInput
+  DetectLanguageInput
 } from "./generated/models";
 import {
   DetectLanguageResult,
@@ -33,7 +33,7 @@ export interface DetectLanguageResultArray extends Array<DetectLanguageResult> {
 }
 
 export function makeDetectLanguageResultArray(
-  input: LanguageInput[],
+  input: DetectLanguageInput[],
   documents: DocumentLanguage[],
   errors: DocumentError[],
   modelVersion: string,

sdk/textanalytics/ai-text-analytics/src/extractKeyPhrasesResultArray.ts

@@ -5,7 +5,7 @@ import {
   TextDocumentBatchStatistics,
   DocumentError,
   DocumentKeyPhrases,
-  MultiLanguageInput
+  TextDocumentInput
 } from "./generated/models";
 import {
   ExtractKeyPhrasesResult,
@@ -33,7 +33,7 @@ export interface ExtractKeyPhrasesResultArray extends Array<ExtractKeyPhrasesRes
 }
 
 export function makeExtractKeyPhrasesResultArray(
-  input: MultiLanguageInput[],
+  input: TextDocumentInput[],
   documents: DocumentKeyPhrases[],
   errors: DocumentError[],
   modelVersion: string,

sdk/textanalytics/ai-text-analytics/src/generated/models/index.ts

@@ -10,9 +10,11 @@
 import * as coreHttp from "@azure/core-http";
 
 /**
- * Contains an input document to be analyzed by the service.
+ * An object representing an individual text document to be analyzed by the Text Analytics service.
+ * The document contains a unique document ID, the full text of the document, and the language of
+ * the document's text.
  */
-export interface MultiLanguageInput {
+export interface TextDocumentInput {
   /**
    * A unique, non-empty document identifier.
    */
@@ -35,7 +37,7 @@ export interface MultiLanguageBatchInput {
   /**
    * The set of documents to process as part of this batch.
    */
-  documents: MultiLanguageInput[];
+  documents: TextDocumentInput[];
 }
 
 /**
@@ -108,7 +110,7 @@ export interface DocumentError {
 }
 
 /**
- * An interface representing TextAnalyticsWarning.
+ * Represents a warning encountered while processing a document.
  */
 export interface TextAnalyticsWarning {
   /**
@@ -122,8 +124,8 @@ export interface TextAnalyticsWarning {
 }
 
 /**
- * if showStats=true was specified in the request this field will contain information about the
- * document payload.
+ * if includeStatistics=true was specified in the request this field will contain information about
+ * the document payload.
  */
 export interface TextDocumentStatistics {
   /**
@@ -147,7 +149,9 @@ export interface SentimentConfidenceScores {
 }
 
 /**
- * An interface representing SentenceSentiment.
+ * The predicted sentiment for a given span of text. For more information regarding text sentiment,
+ * see
+ * https://docs.microsoft.com/en-us/azure/cognitive-services/Text-Analytics/how-tos/text-analytics-how-to-sentiment-analysis.
  */
 export interface SentenceSentiment {
   /**
@@ -194,8 +198,8 @@ export interface DocumentSentiment {
 }
 
 /**
- * if showStats=true was specified in the request this field will contain information about the
- * request payload.
+ * if includeStatistics=true was specified in the request this field will contain information about
+ * the request payload.
  */
 export interface TextDocumentBatchStatistics {
   /**
@@ -238,7 +242,9 @@ export interface SentimentResponse {
 }
 
 /**
- * An interface representing Entity.
+ * A word or phrase identified as an entity that is categorized within a taxonomy of types. The set
+ * of categories recognized by the Text Analytics service is described at
+ * https://docs.microsoft.com/en-us/azure/cognitive-services/Text-Analytics/named-entity-types .
  */
 export interface Entity {
   /**
@@ -302,7 +308,8 @@ export interface EntitiesResult {
 }
 
 /**
- * An interface representing Match.
+ * Details about the specific substring in a document that refers to a linked entity identified by
+ * the Text Analytics model.
  */
 export interface Match {
   /**
@@ -317,7 +324,8 @@ export interface Match {
 }
 
 /**
- * An interface representing LinkedEntity.
+ * A word or phrase identified as a well-known entity within a database, including its formal
+ * (disambiguated) name and a link to the entity information within the source database.
  */
 export interface LinkedEntity {
   /**
@@ -432,9 +440,11 @@ export interface KeyPhraseResult {
 }
 
 /**
- * An interface representing LanguageInput.
+ * An input to the language detection operation. This object specifies a unique document id, as
+ * well as the full text of a document and a hint indicating the document's country of origin to
+ * assist the text analytics predictive model in detecting the document's language.
  */
-export interface LanguageInput {
+export interface DetectLanguageInput {
   /**
    * Unique, non-empty document identifier.
    */
@@ -447,11 +457,11 @@ export interface LanguageInput {
  * An interface representing LanguageBatchInput.
  */
 export interface LanguageBatchInput {
-  documents: LanguageInput[];
+  documents: DetectLanguageInput[];
 }
 
 /**
- * An interface representing DetectedLanguage.
+ * Information about the language of a document as identified by the Text Analytics service.
  */
 export interface DetectedLanguage {
   /**

sdk/textanalytics/ai-text-analytics/src/generated/models/mappers.ts

@@ -9,11 +9,11 @@
 import * as coreHttp from "@azure/core-http";
 
 
-export const MultiLanguageInput: coreHttp.CompositeMapper = {
-  serializedName: "MultiLanguageInput",
+export const TextDocumentInput: coreHttp.CompositeMapper = {
+  serializedName: "TextDocumentInput",
   type: {
     name: "Composite",
-    className: "MultiLanguageInput",
+    className: "TextDocumentInput",
     modelProperties: {
       id: {
         required: true,
@@ -53,7 +53,7 @@ export const MultiLanguageBatchInput: coreHttp.CompositeMapper = {
           element: {
             type: {
               name: "Composite",
-              className: "MultiLanguageInput"
+              className: "TextDocumentInput"
             }
           }
         }
@@ -896,11 +896,11 @@ export const KeyPhraseResult: coreHttp.CompositeMapper = {
   }
 };
 
-export const LanguageInput: coreHttp.CompositeMapper = {
-  serializedName: "LanguageInput",
+export const DetectLanguageInput: coreHttp.CompositeMapper = {
+  serializedName: "DetectLanguageInput",
   type: {
     name: "Composite",
-    className: "LanguageInput",
+    className: "DetectLanguageInput",
     modelProperties: {
       id: {
         required: true,
@@ -940,7 +940,7 @@ export const LanguageBatchInput: coreHttp.CompositeMapper = {
           element: {
             type: {
               name: "Composite",
-              className: "LanguageInput"
+              className: "DetectLanguageInput"
             }
           }
         }

sdk/textanalytics/ai-text-analytics/src/index.ts

@@ -57,8 +57,8 @@ export {
   DetectedLanguage,
   TextDocumentStatistics,
   SentimentConfidenceScores,
-  MultiLanguageInput as TextDocumentInput,
-  LanguageInput as DetectLanguageInput,
+  TextDocumentInput,
+  DetectLanguageInput,
   TextDocumentBatchStatistics,
   Entity,
   SentenceSentiment,

sdk/textanalytics/ai-text-analytics/src/recognizeCategorizedEntitiesResultArray.ts

@@ -5,7 +5,7 @@ import {
   TextDocumentBatchStatistics,
   DocumentError,
   DocumentEntities,
-  MultiLanguageInput
+  TextDocumentInput
 } from "./generated/models";
 import {
   RecognizeCategorizedEntitiesResult,
@@ -34,7 +34,7 @@ export interface RecognizeCategorizedEntitiesResultArray
 }
 
 export function makeRecognizeCategorizedEntitiesResultArray(
-  input: MultiLanguageInput[],
+  input: TextDocumentInput[],
   documents: DocumentEntities[],
   errors: DocumentError[],
   modelVersion: string,

sdk/textanalytics/ai-text-analytics/src/recognizeLinkedEntitiesResultArray.ts

@@ -5,7 +5,7 @@ import {
   TextDocumentBatchStatistics,
   DocumentError,
   DocumentLinkedEntities,
-  MultiLanguageInput
+  TextDocumentInput
 } from "./generated/models";
 import {
   RecognizeLinkedEntitiesResult,
@@ -34,7 +34,7 @@ export interface RecognizeLinkedEntitiesResultArray
 }
 
 export function makeRecognizeLinkedEntitiesResultArray(
-  input: MultiLanguageInput[],
+  input: TextDocumentInput[],
   documents: DocumentLinkedEntities[],
   errors: DocumentError[],
   modelVersion: string,

sdk/textanalytics/ai-text-analytics/src/textAnalyticsClient.ts

@@ -15,10 +15,7 @@ import { TokenCredential, KeyCredential } from "@azure/core-auth";
 import { SDK_VERSION } from "./constants";
 import { GeneratedClient } from "./generated/generatedClient";
 import { logger } from "./logger";
-import {
-  LanguageInput as DetectLanguageInput,
-  MultiLanguageInput as TextDocumentInput
-} from "./generated/models";
+import { DetectLanguageInput, TextDocumentInput } from "./generated/models";
 import {
   DetectLanguageResultArray,
   makeDetectLanguageResultArray

sdk/textanalytics/ai-text-analytics/swagger/README.md

@@ -121,6 +121,12 @@ directive:
       if ($.name === "showStats") {
         $["x-ms-client-name"] = "includeStatistics";
       }
+  - from: swagger-document
+    where: $.definitions[*]
+    transform: >
+      if ($.description && $.description.includes("showStats")) {
+        $.description = $.description.replace("showStats", "includeStatistics");
+      }
 ```
 
 ### Rename {Document,Sentence}SentimentValue -> Label 
@@ -227,3 +233,61 @@ directive:
       delete $["targetRef"];
 ```
 
+### Rename text input objects to avoid "export as"
+
+```yaml
+directive:
+  - from: swagger-document
+    where: $.definitions
+    transform: >
+      if (!$.TextDocumentInput) {
+          $.TextDocumentInput = $.MultiLanguageInput;
+          delete $.MultiLanguageInput;
+      }
+  - from: swagger-document
+    where: $.definitions.MultiLanguageBatchInput.properties.documents.items
+    transform: >
+      $["$ref"] = "#/definitions/TextDocumentInput";
+  - from: swagger-document
+    where: $.definitions
+    transform: >
+      if (!$.DetectLanguageInput) {
+          $.DetectLanguageInput = $.LanguageInput;
+          delete $.LanguageInput;
+      }
+  - from: swagger-document
+    where: $.definitions.LanguageBatchInput.properties.documents.items
+    transform: >
+      $["$ref"] = "#/definitions/DetectLanguageInput";
+```
+
+### Enhance documentation strings for some exported swagger types
+
+```yaml
+directive:
+  - from: swagger-document
+    where: $.definitions.TextAnalyticsWarning
+    transform: $.description = "Represents a warning encountered while processing a document."
+  - from: swagger-document
+    where: $.definitions.SentenceSentiment
+    transform: $.description = "The predicted sentiment for a given span of text. For more information regarding text sentiment, see https://docs.microsoft.com/en-us/azure/cognitive-services/Text-Analytics/how-tos/text-analytics-how-to-sentiment-analysis."
+  - from: swagger-document
+    where: $.definitions.Match
+    transform: $.description = "Details about the specific substring in a document that refers to a linked entity identified by the Text Analytics model."
+  - from: swagger-document
+    where: $.definitions.Entity
+    transform: $.description = "A word or phrase identified as an entity that is categorized within a taxonomy of types. The set of categories recognized by the Text Analytics service is described at https://docs.microsoft.com/en-us/azure/cognitive-services/Text-Analytics/named-entity-types ."
+  - from: swagger-document
+    where: $.definitions.LinkedEntity
+    transform: $.description = "A word or phrase identified as a well-known entity within a database, including its formal (disambiguated) name and a link to the entity information within the source database."
+  - from: swagger-document
+    where: $.definitions.DetectLanguageInput
+    transform: $.description = "An input to the language detection operation. This object specifies a unique document id, as well as the full text of a document and a hint indicating the document's country of origin to assist the text analytics predictive model in detecting the document's language."
+  - from: swagger-document
+    where: $.definitions.TextDocumentInput
+    transform: $.description = "An object representing an individual text document to be analyzed by the Text Analytics service. The document contains a unique document ID, the full text of the document, and the language of the document's text."
+  - from: swagger-document
+    where: $.definitions.DetectedLanguage
+    transform: $.description = "Information about the language of a document as identified by the Text Analytics service."
+```
+