Update doc (#21748)

* Update doc

* Remove suppress

* Remove suppress

* Remove suppress

* Add ad openapi description

* Update typo

Co-authored-by: jr-MS <81400625+jr-MS@users.noreply.github.com>

Author: minkefusiji

specification/cognitiveservices/AnomalyDetector/multivariate/models.cadl

@@ -71,6 +71,7 @@ model MultivariateBatchDetectionResultSummary {
 
   @doc("Error message when detection is failed.")
   errors?: ErrorResponse[];
+  @doc("Variable Status.")
   variableStates?: VariableState[];
 
   @doc("""
@@ -80,6 +81,7 @@ will need another API to get detection results.
   setupInfo: MultivariateBatchDetectionOptions;
 }
 
+@doc("ErrorResponse contains code and message that shows the error information.")
 @error
 model ErrorResponse {
 
@@ -90,6 +92,7 @@ model ErrorResponse {
   message: string;
 }
 
+@doc("Variable Status.")
 model VariableState {
   @doc("Variable name in variable states.")
   variable?: string;
@@ -142,15 +145,18 @@ be date-time of ISO 8601 format.
   endTime: zonedDateTime;
 }
 
+@doc("Anomaly status and information.")
 model AnomalyState {
   @doc("The timestamp for this anomaly.")
   timestamp: zonedDateTime;
+  @doc("The detailed value of this anomalous timestamp.")
   value?: AnomalyValue;
 
   @doc("Error message for the current timestamp.")
   errors?: ErrorResponse[];
 }
 
+@doc("Detailed information of the anomalous timestamp.")
 model AnomalyValue {
   @doc("True if an anomaly is detected at the current timestamp.")
   isAnomaly: boolean;
@@ -170,9 +176,11 @@ well.
   @minValue(0.0)
   @maxValue(2.0)
   score: float32;
+  @doc("Interpretation of this anomalous timestamp.")
   interpretation?: AnomalyInterpretation[];
 }
 
+@doc("Interpretation of the anomalous timestamp.")
 model AnomalyInterpretation {
   @doc("Variable.")
   variable?: string;
@@ -182,9 +190,11 @@ This score shows the percentage contributing to the anomalous timestamp. A
 number between 0 and 1.
 """)
   contributionScore?: float32;
+  @doc("Correlation changes among the anomalous variables")
   correlationChanges?: CorrelationChanges;
 }
 
+@doc("Correlation changes among the anomalous variables")
 model CorrelationChanges {
   @doc("The correlated variables that have correlation changes under an anomaly.")
   changedVariables?: string[];
@@ -267,10 +277,13 @@ Previous, Subsequent, Linear, Zero, Fixed.
 
 @doc("Diagnostics information to help inspect the states of model or variable.")
 model DiagnosticsInfo {
+  @doc("Model status.")
   modelState?: ModelState;
+  @doc("Variable Status.")
   variableStates?: VariableState[];
 }
 
+@doc("Model status.")
 model ModelState {
   @doc("""
 This indicates the number of passes of the entire training dataset the
@@ -333,6 +346,7 @@ model ModelList {
   nextLink?: string;
 }
 
+@doc("Request of last detection.")
 model MultivariateLastDetectionOptions {
   @doc("""
 This contains the inference data, including the name, timestamps(ISO 8601) and
@@ -348,6 +362,7 @@ variables for one anomalous timestamp in the response. The default number is
   topContributorCount: int32;
 }
 
+@doc("Variable values.")
 model VariableValues {
   @doc("Variable name of last detection request.")
   variable: string;
@@ -359,8 +374,12 @@ model VariableValues {
   values: float32[];
 }
 
+
+@doc("Results of last detection.")
 model MultivariateLastDetectionResult {
+  @doc("Variable Status.")
   variableStates?: VariableState[];
+  @doc("Anomaly status and information.")
   results?: AnomalyState[];
 }
 

specification/cognitiveservices/AnomalyDetector/multivariate/routes.cadl

@@ -17,6 +17,7 @@ resultId returned by the BatchDetectAnomaly api.
 // To improve CADL implementation apply: https://github.com/Azure/azure-rest-api-specs/issues/21527
 op GetMultivariateBatchDetectionResult(
   @format("uuid")
+  @doc("ID of a batch detection result.")
   @path resultId: string,
 ): MultivariateDetectionResult | ResponseError;
 
@@ -35,6 +36,7 @@ timestamp column.
 """)
 // To improve CADL implementation apply: https://github.com/Azure/azure-rest-api-specs/issues/21527
 op TrainMultivariateModel(
+  @doc("Model information.")
   @body modelInfo: ModelInfo,
 ): {
   @statusCode statusCode: 201,
@@ -103,6 +105,7 @@ op DetectMultivariateBatchAnomaly(
   @doc("Model identifier.")
   @path
   modelId: string,
+  @doc("Request of multivariate anomaly detection.")
   @body options: MultivariateBatchDetectionOptions,
 ): {
   @statusCode statusCode: 202,
@@ -126,5 +129,6 @@ op DetectMultivariateLastAnomaly(
   @doc("Model identifier.")
   @path
   modelId: string,
+  @doc("Request of last detection.")
   @body options: MultivariateLastDetectionOptions,
 ): MultivariateLastDetectionResult | ResponseError;

specification/cognitiveservices/AnomalyDetector/univariate/models.cadl

@@ -178,6 +178,7 @@ sever the anomaly is. For normal points, the \"severity\" is always 0.
 @error
 model AnomalyDetectorError {
   @header
+  @doc("Error code.")
   "x-ms-error-code"?: string,
 
   @doc("The error code.")

specification/cognitiveservices/AnomalyDetector/univariate/routes.cadl

@@ -18,6 +18,7 @@ user an overall status of the time series.
 """)
 // To improve CADL implementation apply: https://github.com/Azure/azure-rest-api-specs/issues/21527
 op DetectUnivariateEntireSeries(
+  @doc("Method of univariate anomaly detection.")
   @body options: UnivariateDetectionOptions,
 ): UnivariateEntireDetectionResult | AnomalyDetectorError;
 
@@ -30,6 +31,7 @@ and based on all data to determine whether the last point is anomalous.
 """)
 // To improve CADL implementation apply: https://github.com/Azure/azure-rest-api-specs/issues/21527
 op DetectUnivariateLastPoint(
+  @doc("Method of univariate anomaly detection.")
   @body options: UnivariateDetectionOptions,
 ): UnivariateLastDetectionResult | AnomalyDetectorError;
 
@@ -39,5 +41,6 @@ op DetectUnivariateLastPoint(
 @doc("Evaluate change point score of every series point")
 // To improve CADL implementation apply: https://github.com/Azure/azure-rest-api-specs/issues/21527
 op DetectUnivariateChangePoint(
+  @doc("Method of univariate anomaly detection.")
   @body options: UnivariateChangePointDetectionOptions,
 ): UnivariateChangePointDetectionResult | AnomalyDetectorError;