From 80785f75a7bb1f690661b96fc4cf6b44221343f4 Mon Sep 17 00:00:00 2001
From: lcawl <lcawley@elastic.co>
Date: Tue, 23 May 2023 17:15:25 -0700
Subject: [PATCH 1/2] [DOCS] Add cat aliases descriptions

---
 specification/cat/aliases/CatAliasesRequest.ts | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/specification/cat/aliases/CatAliasesRequest.ts b/specification/cat/aliases/CatAliasesRequest.ts
index 319ee52ceb..27b415d4c1 100644
--- a/specification/cat/aliases/CatAliasesRequest.ts
+++ b/specification/cat/aliases/CatAliasesRequest.ts
@@ -21,13 +21,17 @@ import { CatRequestBase } from '@cat/_types/CatBase'
 import { ExpandWildcards, Names } from '@_types/common'
 
 /**
+ * Retrieves the cluster’s index aliases, including filter and routing information.
+ * The API does not return data stream aliases.
  * @rest_spec_name cat.aliases
  * @since 0.0.0
  * @stability stable
  * @doc_id cat-alias
+ * @index_privileges view_index_metadata, manage
  */
 export interface Request extends CatRequestBase {
   path_parts: {
+    /** A comma-separated list of aliases to retrieve. Supports wildcards (`*`).  To retrieve all aliases, omit this parameter or use `*` or `_all`. */
     name?: Names
   }
   query_parameters: {

From 982952245c82ee1c587e223017bf7fe45508c05d Mon Sep 17 00:00:00 2001
From: lcawl <lcawley@elastic.co>
Date: Tue, 23 May 2023 17:25:22 -0700
Subject: [PATCH 2/2] [DOCS] Adds cat allocation descriptions

---
 .../cat/aliases/CatAliasesRequest.ts          |  1 +
 .../cat/allocation/CatAllocationRequest.ts    |  5 ++++
 specification/cat/allocation/types.ts         | 24 ++++++++++++-------
 3 files changed, 21 insertions(+), 9 deletions(-)

diff --git a/specification/cat/aliases/CatAliasesRequest.ts b/specification/cat/aliases/CatAliasesRequest.ts
index 27b415d4c1..3868b96a0c 100644
--- a/specification/cat/aliases/CatAliasesRequest.ts
+++ b/specification/cat/aliases/CatAliasesRequest.ts
@@ -23,6 +23,7 @@ import { ExpandWildcards, Names } from '@_types/common'
 /**
  * Retrieves the cluster’s index aliases, including filter and routing information.
  * The API does not return data stream aliases.
+ * IMPORTANT: cat APIs are only intended for human consumption using the command line or the Kibana console. They are not intended for use by applications. For application consumption, use the aliases API.
  * @rest_spec_name cat.aliases
  * @since 0.0.0
  * @stability stable
diff --git a/specification/cat/allocation/CatAllocationRequest.ts b/specification/cat/allocation/CatAllocationRequest.ts
index a4d8de3d90..2637481d74 100644
--- a/specification/cat/allocation/CatAllocationRequest.ts
+++ b/specification/cat/allocation/CatAllocationRequest.ts
@@ -21,16 +21,21 @@ import { CatRequestBase } from '@cat/_types/CatBase'
 import { Bytes, NodeIds } from '@_types/common'
 
 /**
+ * Provides a snapshot of the number of shards allocated to each data node and their disk space.
+ * IMPORTANT: cat APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications.
  * @rest_spec_name cat.allocation
  * @since 0.0.0
  * @stability stable
  * @doc_id cat-allocation
+ * @cluster_privileges monitor, manage
  */
 export interface Request extends CatRequestBase {
   path_parts: {
+    /** Comma-separated list of node identifiers or names used to limit the returned information. */
     node_id?: NodeIds
   }
   query_parameters: {
+    /** The unit used to display byte values. */
     bytes?: Bytes
   }
 }
diff --git a/specification/cat/allocation/types.ts b/specification/cat/allocation/types.ts
index 09067d4583..004fe44b02 100644
--- a/specification/cat/allocation/types.ts
+++ b/specification/cat/allocation/types.ts
@@ -23,46 +23,52 @@ import { Percentage } from '@_types/Numeric'
 
 export class AllocationRecord {
   /**
-   * number of shards on node
+   * Number of primary and replica shards assigned to the node.
    * @aliases s
    */
   shards?: string
   /**
-   * disk used by ES indices
+   * Disk space used by the node’s shards. Does not include disk space for the translog or unassigned shards.
+   * IMPORTANT: This metric double-counts disk space for hard-linked files, such as those created when shrinking, splitting, or cloning an index.
    * @aliases di,diskIndices
    */
   'disk.indices'?: ByteSize | null
   /**
-   * disk used (total, not just ES)
+   * Total disk space in use.
+   * Elasticsearch retrieves this metric from the node’s operating system (OS).
+   * The metric includes disk space for: Elasticsearch, including the translog and unassigned shards; the node’s operating system; any other applications or files on the node.
+   * Unlike `disk.indices`, this metric does not double-count disk space for hard-linked files.
    * @aliases du,diskUsed
    */
   'disk.used'?: ByteSize | null
   /**
-   * disk available
+   * Free disk space available to Elasticsearch.
+   * Elasticsearch retrieves this metric from the node’s operating system.
+   * Disk-based shard allocation uses this metric to assign shards to nodes based on available disk space.
    * @aliases da,diskAvail
    */
   'disk.avail'?: ByteSize | null
   /**
-   * total capacity of all volumes
+   * Total disk space for the node, including in-use and available space.
    * @aliases dt,diskTotal
    */
   'disk.total'?: ByteSize | null
   /**
-   * percent disk used
+   * Total percentage of disk space in use. Calculated as `disk.used / disk.total`.
    * @aliases dp,diskPercent
    */
   'disk.percent'?: Percentage | null
   /**
-   * host of node
+   * Network host for the node. Set using the `network.host` setting.
    * @aliases h
    */
   host?: Host | null
   /**
-   * ip of node
+   * IP address and port for the node.
    */
   ip?: Ip | null
   /**
-   * name of node
+   * Name for the node. Set using the `node.name` setting.
    * @aliases n
    */
   node?: string