[docs] Document hidden equality/hashing behavior (apple#618)

* [docs] Document `hidden` equality/hashing behavior

* Update docs/modules/language-reference/pages/index.adoc

---------

Co-authored-by: Daniel Chao <daniel.h.chao@gmail.com>

docs/modules/language-reference/pages/index.adoc

@@ -915,6 +915,7 @@ pigeon = new Dynamic { // <1>
 ==== Hidden Properties
 
 A property with the modifier `hidden` is omitted from the rendered output and object conversions.
+Hidden properties are also ignored when evaluating equality or hashing (e.g. for `Mapping` or `Map` keys).
 
 [source,{pkl}]
 ----
@@ -933,12 +934,19 @@ pigeon = new Bird { // <3>
 pigeonInIndex = pigeon.nameAndLifespanInIndex // <4>
 
 pigeonDynamic = pigeon.toDynamic() // <5>
+
+favoritePigeon = (pigeon) {
+  nameAndLifespanInIndex = "Bettie, \(lifespan)"
+}
+
+samePigeon = pigeon == favoritePigeon // <6>
 ----
 <1> Properties defined as `hidden` are accessible on any `Bird` instance, but not output by default.
 <2> Non-hidden properties can refer to hidden properties as usual.
 <3> `pigeon` is an object with _four_ properties, but is rendered with _three_ properties.
 <4> Accessing a `hidden` property from outside the class and object is like any other property.
 <5> Object conversions omit hidden properties, so the resulting `Dynamic` has three properties.
+<6> Objects that differ only in `hidden` property values are considered equal
 
 Invoking Pkl on this file produces the following result.
 
@@ -955,6 +963,12 @@ pigeonDynamic {
   lifespan = 8
   nameSignWidth = 9
 }
+favoritePigeon {
+  name = "Pigeon"
+  lifespan = 8
+  nameSignWidth = 9
+}
+samePigeon = true
 ----
 
 ==== Local properties