[Docs] Descriptions for rank eval and mterm parameters (#622)

Signed-off-by: Archer <[email protected]>

spec/schemas/_core.mtermvectors.yaml

@@ -14,23 +14,23 @@ components:
  _index:
  $ref: '_common.yaml#/components/schemas/IndexName'
  doc:
- description: An artificial document (a document not present in the index) for which you want to retrieve term vectors. 
+ description: An artificial document for which you want to retrieve term vectors. 
  type: object
  fields:
  $ref: '_common.yaml#/components/schemas/Fields'
  field_statistics:
- description: When `true`, the response includes the document count, the sum of document frequencies, and the sum of term frequencies.
+ description: When `true`, the response includes the document count, the sum of the document frequencies, and the sum of the term frequencies.
  type: boolean
  filter:
  $ref: '_core.termvectors.yaml#/components/schemas/Filter'
  offsets:
- description: When `true`, the response includes term offsets.
+ description: When `true`, the response includes the term offsets.
  type: boolean
  payloads:
- description: When `true`, the response includes term payloads.
+ description: When `true`, the response includes the term payloads.
  type: boolean
  positions:
- description: When `true`, the response includes term positions.
+ description: When `true`, the response includes the term positions.
  type: boolean
  routing:
  $ref: '_common.yaml#/components/schemas/Routing'

spec/schemas/_core.rank_eval.yaml

@@ -14,7 +14,7 @@ components:
  request:
  $ref: '#/components/schemas/RankEvalQuery'
  ratings:
- description: List of document ratings
+ description: A list of document ratings.
  type: array
  items:
  $ref: '#/components/schemas/DocumentRating'
@@ -45,7 +45,7 @@ components:
  _index:
  $ref: '_common.yaml#/components/schemas/IndexName'
  rating:
- description: The document's relevance with regard to this search request.
+ description: The document's relevance with regard to the specified search request.
  type: number
  required:
  - _id
@@ -70,21 +70,21 @@ components:
  - type: object
  properties:
  ignore_unlabeled:
- description: Controls how unlabeled documents in the search results are counted. If set to true, unlabeled documents are ignored and neither count as relevant or irrelevant. Set to false (the default), they are treated as irrelevant.
+ description: Controls how unlabeled documents in the search results are counted. When `true`, unlabeled documents are ignored and do not count as relevant or irrelevant. When `false`, unlabeled documents are treated as irrelevant.
  type: boolean
  RankEvalMetricRatingThreshold:
  allOf:
  - $ref: '#/components/schemas/RankEvalMetricBase'
  - type: object
  properties:
  relevant_rating_threshold:
- description: Sets the rating threshold above which documents are considered to be "relevant".
+ description: Sets the rating threshold above which documents are considered to be relevant.
  type: number
  RankEvalMetricBase:
  type: object
  properties:
  k:
- description: Sets the maximum number of documents retrieved per query. This value will act in place of the usual size parameter in the query.
+ description: Sets the maximum number of documents retrieved per query. This value replaces the usual `size` parameter in the query.
  type: number
  RankEvalMetricRecall:
  allOf:
@@ -100,7 +100,7 @@ components:
  - type: object
  properties:
  normalize:
- description: If set to true, this metric will calculate the Normalized DCG (https://en.wikipedia.org/wiki/Discounted_cumulative_gain#Normalized_DCG).
+ description: When `true`, this metric calculates the Normalized DCG (https://en.wikipedia.org/wiki/Discounted_cumulative_gain#Normalized_DCG).
  type: boolean
  RankEvalMetricExpectedReciprocalRank:
  allOf:
@@ -116,20 +116,20 @@ components:
  type: object
  properties:
  metric_score:
- description: The metric_score in the details section shows the contribution of this query to the global quality metric score
+ description: The `metric_score`, found in the `metric_details` section, shows the contribution of this query to the global quality metric score.
  type: number
  unrated_docs:
- description: The unrated_docs section contains an _index and _id entry for each document in the search result for this query that didn't have a ratings value. This can be used to ask the user to supply ratings for these documents
+ description: The `unrated_docs` section contains an `_index` and `_id` entry for each document that didn't have a ratings value. This can be used to ask the user to supply ratings for these documents.
  type: array
  items:
  $ref: '#/components/schemas/UnratedDocument'
  hits:
- description: The hits section shows a grouping of the search results with their supplied ratings
+ description: The `hits` section shows a grouping of the search results with their supplied ratings
  type: array
  items:
  $ref: '#/components/schemas/RankEvalHitItem'
  metric_details:
- description: The metric_details give additional information about the calculated quality metric (e.g. how many of the retrieved documents were relevant). The content varies for each metric but allows for better interpretation of the results
+ description: The `metric_details` section gives additional information about the calculated quality metric, in other words, how many of the retrieved documents were relevant. The content varies for each metric but allows for better interpretation of the results.
  type: object
  additionalProperties:
  type: object