[DOCS] Reformat match phrase prefix query (#45209)

docs/reference/analysis.asciidoc

@@ -32,6 +32,7 @@ to the inverted index:
 ------
 
 [float]
+[[specify-index-time-analyzer]]
 === Specifying an index time analyzer
 
 Each <<text,`text`>> field in a mapping can specify its own

docs/reference/query-dsl/match-phrase-prefix-query.asciidoc

@@ -4,27 +4,19 @@
 <titleabbrev>Match phrase prefix</titleabbrev>
 ++++
 
-The `match_phrase_prefix` is the same as `match_phrase`, except that it
-allows for prefix matches on the last term in the text. For example:
+Returns documents that contain the words of a provided text, in the **same
+order** as provided. The last term of the provided text is treated as a
+<<query-dsl-prefix-query,prefix>>, matching any words that begin with that term.
 
-[source,js]
---------------------------------------------------
-GET /_search
-{
-    "query": {
-        "match_phrase_prefix" : {
-            "message" : "quick brown f"
-        }
-    }
-}
---------------------------------------------------
-// CONSOLE
 
-It accepts the same parameters as the phrase type. In addition, it also
-accepts a `max_expansions` parameter (default `50`) that can control to how
-many suffixes the last term will be expanded. It is highly recommended to set
-it to an acceptable value to control the execution time of the query. For
-example:
+[[match-phrase-prefix-query-ex-request]]
+==== Example request
+
+The following search returns documents that contain phrases beginning with
+`quick brown f` in the `message` field.
+
+This search would match a `message` value of `quick brown fox` or `two quick
+brown ferrets` but not `the fox is quick and brown`.
 
 [source,js]
 --------------------------------------------------
@@ -33,8 +25,7 @@ GET /_search
     "query": {
         "match_phrase_prefix" : {
             "message" : {
-                "query" : "quick brown f",
-                "max_expansions" : 10
+                "query" : "quick brown f"
             }
         }
     }
@@ -42,26 +33,72 @@ GET /_search
 --------------------------------------------------
 // CONSOLE
 
-[IMPORTANT]
-===================================================
 
-The `match_phrase_prefix` query is a poor-man's autocomplete.  It is very easy
-to use, which lets you get started quickly with _search-as-you-type_ but its
-results, which usually are good enough,  can sometimes be confusing.
+[[match-phrase-prefix-top-level-params]]
+==== Top-level parameters for `match_phrase_prefix`
+`<field>`::
+(Required, object) Field you wish to search.
 
-Consider the query string `quick brown f`.  This query works by creating a
-phrase query out of `quick` and `brown` (i.e. the term `quick` must exist and
-must be followed by the term `brown`).  Then it looks at the sorted term
-dictionary to find the first 50 terms that begin with `f`, and
-adds these terms to the phrase query.
+[[match-phrase-prefix-field-params]]
+==== Parameters for `<field>`
+`query`::
++
+--
+(Required, string) Text you wish to find in the provided `<field>`. 
+
+The `match_phrase_prefix` query <<analysis,analyzes>> any provided text into
+tokens before performing a search. The last term of this text is treated as a
+<<query-dsl-prefix-query,prefix>>, matching any words that begin with that term.
+--
+
+`analyzer`::
+(Optional, string) <<analysis,Analyzer>> used to convert text in the `query`
+value into tokens. Defaults to the <<specify-index-time-analyzer,index-time
+analyzer>> mapped for the `<field>`. If no analyzer is mapped, the index's
+default analyzer is used.
+
+`max_expansions`::
+(Optional, integer) Maximum number of terms to which the last provided term of
+the `query` value will expand. Defaults to `50`.
+
+`slop`::
+(Optional, integer) Maximum number of positions allowed between matching tokens.
+Defaults to `0`. Transposed terms have a slop of `2`.
+
+`zero_terms_query`::
++
+--
+(Optional, string) Indicates whether no documents are returned if the `analyzer`
+removes all tokens, such as when using a `stop` filter. Valid values are:
+
+ `none` (Default)::
+No documents are returned if the `analyzer` removes all tokens.
+
+ `all`::
+Returns all documents, similar to a <<query-dsl-match-all-query,`match_all`>>
+query.
+--
+
+
+[[match-phrase-prefix-query-notes]]
+==== Notes
+
+[[match-phrase-prefix-autocomplete]]
+===== Using the match phrase prefix query for search autocompletion
+While easy to set up, using the `match_phrase_prefix` query for search
+autocompletion can sometimes produce confusing results.
+
+For example, consider the query string `quick brown f`. This query works by
+creating a phrase query out of `quick` and `brown` (i.e. the term `quick` must
+exist and must be followed by the term `brown`). Then it looks at the sorted
+term dictionary to find the first 50 terms that begin with `f`, and adds these
+terms to the phrase query.
 
 The problem is that the first 50 terms may not include the term `fox` so the
-phrase `quick brown fox` will not be found.  This usually isn't a problem as
+phrase `quick brown fox` will not be found. This usually isn't a problem as
 the user will continue to type more letters until the word they are looking
 for appears.
 
 For better solutions for _search-as-you-type_ see the
 <<completion-suggester,completion suggester>> and
-the <<search-as-you-type,`search_as_you_type` field type>>.
-
-===================================================
+the <<search-as-you-type,`search_as_you_type` field type>>.