From cd56cae0326c8b53a22ab1a437e0e37d20045813 Mon Sep 17 00:00:00 2001
From: Christian Mazakas <christian.mazakas@gmail.com>
Date: Thu, 6 Jan 2022 15:27:18 -0800
Subject: [PATCH] Update reference docs for `find()` to include heterogeneous
 overloads

---
 doc/ref.php | 46 +++++++++++++++++++++++++++++++++++++++-------
 1 file changed, 39 insertions(+), 7 deletions(-)

diff --git a/doc/ref.php b/doc/ref.php
index 35df3f49..b3a69d75 100644
--- a/doc/ref.php
+++ b/doc/ref.php
@@ -1272,6 +1272,24 @@ EOL;
                 </parameter>
                 <type>const_iterator</type>
               </signature>
+              <signature>
+                <template>
+                  <template-type-parameter name="K" />
+                </template>
+                <parameter name="k">
+                  <paramtype>K const&amp;</paramtype>
+                </parameter>
+                <type>iterator</type>
+              </signature>
+              <signature cv="const">
+                <template>
+                  <template-type-parameter name="K" />
+                </template>
+                <parameter name="k">
+                  <paramtype>K const&amp;</paramtype>
+                </parameter>
+                <type>const_iterator</type>
+              </signature>
               <signature>
                 <template>
                   <template-type-parameter name="CompatibleKey"/>
@@ -1309,13 +1327,27 @@ EOL;
               <returns>
                 <para>An iterator pointing to an element with key equivalent to <code>k</code>, or <code>b.end()</code> if no such element exists.</para>
               </returns>
-              <notes><para>
-                The templated overloads are a non-standard extensions which
-                allows you to use a compatible hash function and equality
-                predicate for a key of a different type in order to avoid
-                an expensive type cast. In general, its use is not encouraged.
-              </para></notes>
-            </overloaded-method>
+              <notes>
+                <para>
+                  The templated overloads containing <code>CompatibleKey</code>,
+                  <code>CompatibleHash</code> and <code>CompatiblePredicate</code>
+                  are non-standard extensions which allow you to use a compatible
+                  hash function and equality predicate for a key of a different type
+                  in order to avoid an expensive type cast. In general, its use is
+                  not encouraged and instead the <code>K</code> member function
+                  templates should be used.
+                </para>
+                <para>
+                  The <code>template &lt;typename K&gt;</code> overloads only participate
+                  in overload resolution if <code>Hash::is_transparent</code> and
+                  <code>Pred::is_transparent</code> are valid member typedefs. The
+                  library assumes that <code>Hash</code> is callable with both
+                  <code>K</code> and <code>Key</code> and that <code>Pred</code> is
+                  transparent. This enables heterogeneous lookup which avoids the cost of
+                  instantiating an instance of the <code>Key</code> type.
+                </para>
+              </notes>
+            </overloaded-method>            
             <method name="count" cv="const">
               <parameter name="k">
                 <paramtype>key_type const&amp;</paramtype>