doc: overhaul std/misc/shared documentation

also, adding deprecation note, since gambit 4.9.1 added similar support to the
regular equal? predicate

doc/reference/misc.md

@@ -3935,15 +3935,19 @@ Please document me!
 :::
 
 ### equal-shared?
-::: tip usage
-```
-(equal-shared? ...)
-```
-:::
+``` scheme
+(equal-shared? a b) -> boolean
 
-Please document me!
+  a, b := structures to check
+```
 
+Checks whether *a* and *b*, two potentially recursive, cyclic or otherwise
+infinite shared structures, e.g. trees or graphs, are equal.
 
+::: warning Deprecation note:
+Gambit 4.9.1 (released 2018-11-16) added similar support for handling shared
+structures with `equal?`, superseding `equal-shared?`.
+:::
 
 ## Shuffling
 ::: tip To use the bindings from this module: