Add notes on usage of type-of()

specifications/xpath-functions-40/src/function-catalog.xml

@@ -699,6 +699,19 @@ $node ! (
          <p>In general, an item matches more than one type, and there are cases where there is no single matching type that
          is more specific than all the others. This is especially true with functions, maps, and arrays. This function therefore
          selects one of the types that matches the item, which is not necessarily the most specific type.</p>
+
+         <p>This function should not be used as a substitute for an <code>instance of</code> test. The precise type annotation
+         of the result of an expression is not always predictable, because processors are free to deliver a more specific type
+         than is mandated by the specification. For example, if <code>$n</code> is of type <code>xs:positiveInteger</code>,
+         then the result of <code>abs($n)</code> is guaranteed to be an instance of <code>xs:integer</code>, but an 
+         implementation might reasonably return the supplied value unchanged: that is, a value whose actual type 
+         annotation is <code>xs:positiveInteger</code>. Similarly the type annotation of the value returned by
+         <code>position()</code> might be <code>xs:long</code> rather than <code>xs:integer</code>.</p>
+
+         <p>Implementations <rfc2119>should</rfc2119>, however, refrain from exposing types that are purely internal.
+         For example, an implementation might have an optimized internal representation for strings consisting entirely
+         of ASCII characters, or for single-character strings; if this is the case then the type annotation returned by this function
+         should be a user-visible supertype such as <code>xs:string</code>.</p>
       </fos:notes>
 
       <fos:examples>
@@ -22368,7 +22381,7 @@ declare function transitive-closure (
          then the result of <code>abs($n)</code> is guaranteed to be an instance of <code>xs:integer</code>, but an 
          implementation might reasonably return the supplied value unchanged: that is, a value whose actual type 
          annotation is <code>xs:positiveInteger</code>. Similarly the type annotation of the value returned by
-         <code>position()</code> might have a type annotation of <code>xs:long</code> rather than <code>xs:integer</code>.</p>
+         <code>position()</code> might be <code>xs:long</code> rather than <code>xs:integer</code>.</p>
 
          <p>Implementations <rfc2119>should</rfc2119>, however, refrain from exposing types that are purely internal.
          For example, an implementation might have an optimized internal representation for strings consisting entirely