From 77d7bb7af0a2aa85d80d75ca0c1a56894aad5ccc Mon Sep 17 00:00:00 2001
From: epriestley <git@epriestley.com>
Date: Sat, 21 Jul 2018 05:23:23 -0700
Subject: [PATCH] Document the Ferret "=" operator and improve related
 documentation

Summary:
Depends on D19529. See PHI778.

  - Document the "name" constraint as deprecated. All callers are likely better served by the "query" constraint.
  - Guide users toward the "query" constraint a little better.
  - Document the `=` syntax.

Test Plan: Read various new documentation.

Reviewers: amckinley

Reviewed By: amckinley

Differential Revision: https://secure.phabricator.com/D19531
---
 .../project/query/PhabricatorProjectSearchEngine.php     | 8 +++++++-
 .../PhabricatorFerretSearchEngineExtension.php           | 5 ++++-
 src/docs/user/userguide/search.diviner                   | 9 +++++++++
 3 files changed, 20 insertions(+), 2 deletions(-)

diff --git a/src/applications/project/query/PhabricatorProjectSearchEngine.php b/src/applications/project/query/PhabricatorProjectSearchEngine.php
index e38532c419..02e795395a 100644
--- a/src/applications/project/query/PhabricatorProjectSearchEngine.php
+++ b/src/applications/project/query/PhabricatorProjectSearchEngine.php
@@ -22,7 +22,13 @@ final class PhabricatorProjectSearchEngine
     return array(
       id(new PhabricatorSearchTextField())
         ->setLabel(pht('Name'))
-        ->setKey('name'),
+        ->setKey('name')
+        ->setDescription(
+          pht(
+            '(Deprecated.) Search for projects with a given name or '.
+            'hashtag using tokenizer/datasource query matching rules. This '.
+            'is deprecated in favor of the more powerful "query" '.
+            'constraint.')),
       id(new PhabricatorSearchStringListField())
         ->setLabel(pht('Slugs'))
         ->setIsHidden(true)
diff --git a/src/applications/search/engineextension/PhabricatorFerretSearchEngineExtension.php b/src/applications/search/engineextension/PhabricatorFerretSearchEngineExtension.php
index 65822b0a32..55b7c2225a 100644
--- a/src/applications/search/engineextension/PhabricatorFerretSearchEngineExtension.php
+++ b/src/applications/search/engineextension/PhabricatorFerretSearchEngineExtension.php
@@ -57,7 +57,10 @@ final class PhabricatorFerretSearchEngineExtension
     $fields[] = id(new PhabricatorSearchTextField())
       ->setKey('query')
       ->setLabel(pht('Query'))
-      ->setDescription(pht('Fulltext search.'));
+      ->setDescription(
+        pht(
+          'Find objects matching a fulltext search query. See '.
+          '"Search User Guide" in the documentation for details.'));
 
     return $fields;
   }
diff --git a/src/docs/user/userguide/search.diviner b/src/docs/user/userguide/search.diviner
index d1c6182128..f1b32e7dc7 100644
--- a/src/docs/user/userguide/search.diviner
+++ b/src/docs/user/userguide/search.diviner
@@ -138,6 +138,7 @@ some special syntax. These features are supported:
   - Field search with `title:platypus`.
   - Filtering out matches with `-platypus`.
   - Quoted terms with `"platypus attorney"`.
+  - Matching entire fields with `=platypus`.
   - Combining features with `title:~"platypus attorney"`.
 
 See below for more detail.
@@ -173,3 +174,11 @@ or `title:"platypus attorney"`. These scopes are also supported:
 **Filtering Matches**: You can remove documents which match certain terms from
 the result set with `-`. For example: `platypus -mammal`. Documents which match
 negated terms will be filtered out of the result set.
+
+**Matching Entire Fields**: If you know the exact name of an object and want
+to find only that object, you can use the `=` operator. A query like
+`title:"warp drive"` will find a document titled "Warp Drive", but will also
+find documents with longer titles, like "Not a Warp Drive". The `=` operator
+requires that the entire field match the query exactly, so //only// documents
+exactly titled "Warp Drive" will be matched by the query (but note that the
+query is still case insensitive).