[DOCS] Add descriptions for cat aliases and cat allocation

specification/cat/aliases/CatAliasesRequest.ts

@@ -21,13 +21,18 @@ 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.
+ * 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
  * @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: {

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
   }
 }

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