[DOCS] Reformats cat segments API (#45397)

docs/reference/cat/segments.asciidoc

@@ -1,9 +1,109 @@
 [[cat-segments]]
 === cat segments
 
-The `segments` command provides low level information about the segments
+Returns low-level information about the https://lucene.apache.org/core/[Lucene]
-in the shards of an index. It provides information similar to the
+segments in index shards, similar to the <<indices-segments, indices segments>>
-link:indices-segments.html[_segments] endpoint. For example:
+API.
+
+[[cat-segments-api-request]]
+==== {api-request-title}
+
+`GET /_cat/segments/{index}`
+
+
+[[cat-segments-path-params]]
+==== {api-path-parms-title}
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=index]
+
+
+[[cat-segments-query-params]]
+==== {api-query-parms-title}
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=bytes]
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=http-format]
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=cat-h]
++
+--
+If you do not specify which columns to include, the API returns the default
+columns in the order listed below. If you explicitly specify one or more
+columns, it only returns the specified columns.
+
+Valid columns are:
+
+`index`, `i`, `idx`::
+(Default) Name of the index, such as `twitter`.
+
+`shard`, `s`, `sh`::
+(Default) Name of the shard.
+
+`prirep`, `p`, `pr`, `primaryOrReplica`::
+(Default) Shard type. Returned values are `primary` or `replica`.
+
+`ip`::
+(Default) IP address of the segment's shard, such as `127.0.1.1`.
+
+`segment`::
+(Default) Name of the segment, such as `_0`. The segment name is derived from
+the segment generation and used internally to create file names in the directory
+of the shard.
+
+`generation`::
+(Default) Generation number, such as `0`. {es} increments this generation number
+for each segment written. {es} then uses this number to derive the segment name.
+
+`docs.count`::
+(Default) Number of non-deleted documents in the segment, such as `25`. This
+number is based on Lucene documents and may include documents from
+<<nested,nested>> fields.
+                
+`docs.deleted`::
+(Default) Number of deleted documents in the segment, such as `0`. This number
+is based on Lucene documents. {es} reclaims the disk space of deleted Lucene
+documents when a segment is merged.
+
+`size`::
+(Default) Disk space used by the segment, such as `50kb`.
+
+`size.memory`::
+(Default) Bytes of segment data stored in memory for efficient search, such as
+`1264`.
+
+`committed`::
+(Default) If `true`, the segment is committed to disk. Segments committed to
+disk would survive a hard reboot. 
++
+If `false`, the data from uncommitted segments is also stored in the transaction
+log. {es} replays those changes on the next start.
+
+`searchable`::
+(Default) If `true`, the segment is searchable.
++
+If `false`, likely means the segment is written to disk but has not been
+<<docs-refresh,refreshed>>.
+
+`version`::
+(Default) Version of Lucene used to write the segment.
+
+`compound`::
+(Default) If `true`, the segment is stored in a compound file. This means Lucene
+merged all files from the segment in a single file to save file descriptors.
+
+`id`::
+ID of the node, such as `k0zy`.
+--
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=help]
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=cat-s]
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=cat-v]
+
+
+[[cat-shards-api-example]]
+==== {api-examples-title}
 
 [source,js]
 --------------------------------------------------
@@ -12,7 +112,7 @@ GET /_cat/segments?v
 // CONSOLE
 // TEST[s/^/PUT \/test\/test\/1?refresh\n{"test":"test"}\nPUT \/test1\/test\/1?refresh\n{"test":"test"}\n/]
 
-might look like:
+The API returns the following response:
 
 ["source","txt",subs="attributes,callouts"]
 --------------------------------------------------
@@ -21,53 +121,3 @@ test  0     p      127.0.0.1 _0               0          1            0  3kb
 test1 0     p      127.0.0.1 _0               0          1            0  3kb        2042 false     true       {lucene_version}   true
 --------------------------------------------------
 // TESTRESPONSE[s/3kb/\\d+(\\.\\d+)?[mk]?b/ s/2042/\\d+/ non_json]
-
-The output shows information about index names and shard numbers in the first
-two columns.
-
-If you only want to get information about segments in one particular index,
-you can add the index name in the URL, for example `/_cat/segments/test`. Also,
-several indexes can be queried like `/_cat/segments/test,test1`
-
-
-The following columns provide additional monitoring information:
-
-prirep::        Whether this segment belongs to a primary or replica shard.
-
-ip::            The ip address of the segment's shard.
-
-segment::       A segment name, derived from the segment generation. The name
-                is internally used to generate the file names in the directory
-                of the shard this segment belongs to.
-
-generation::    The generation number is incremented with each segment that is written.
-                The name of the segment is derived from this generation number.
-
-docs.count::    The number of non-deleted documents that are stored in this segment.
-                Note that these are Lucene documents, so the count will include hidden
-				documents (e.g. from nested types).
-
-docs.deleted::  The number of deleted documents that are stored in this segment.
-                It is perfectly fine if this number is greater than 0, space is
-                going to be reclaimed when this segment gets merged.
-
-size::          The amount of disk space that this segment uses.
-
-size.memory::   Segments store some data into memory in order to be searchable efficiently.
-                This column shows the number of bytes in memory that are used.
-
-committed::     Whether the segment has been sync'ed on disk. Segments that are
-                committed would survive a hard reboot. No need to worry in case
-                of false, the data from uncommitted segments is also stored in
-                the transaction log so that Elasticsearch is able to replay
-                changes on the next start.
-
-searchable::    True if the segment is searchable. A value of false would most
-                likely mean that the segment has been written to disk but no
-                refresh occurred since then to make it searchable.
-
-version::       The version of Lucene that has been used to write this segment.
-
-compound::      Whether the segment is stored in a compound file. When true, this
-                means that Lucene merged all files from the segment in a single
-                one in order to save file descriptors.