lib/builtin.pm: Document that builtin functions have optimisations which may stop working if the functions are replaced

Author: leonerd

lib/builtin.pm

@@ -1,4 +1,4 @@
-package builtin 0.015;
+package builtin 0.016;
 
 use v5.40;
 
@@ -106,6 +106,13 @@ The following bundles currently exist:
     :5.40      true false weaken unweaken is_weak blessed refaddr reftype
                ceil floor is_tainted trim indexed
 
+=head2 Function Optimisations
+
+There are a number of optimisations that apply to functions in the L<builtin>
+package.  If you replace or override these functions (such as by assignment
+into glob references) the optimisations may not take effect.  Do so with
+caution.
+
 =head1 FUNCTIONS
 
 =head2 true