effects: add docstrings to the type-based-effect-analysis queries (#49222)

Author: aviatesk

base/compiler/typeinfer.jl

@@ -447,7 +447,7 @@ function adjust_effects(sv::InferenceState)
         end
         ipo_effects = Effects(ipo_effects; inaccessiblememonly=ALWAYS_TRUE)
     end
-    if is_consistent_if_notreturned(ipo_effects) && is_consistent_argtype(rt)
+    if is_consistent_if_notreturned(ipo_effects) && is_identity_free_argtype(rt)
         # in a case when the :consistent-cy here is only tainted by mutable allocations
         # (indicated by `CONSISTENT_IF_NOTRETURNED`), we may be able to refine it if the return
         # type guarantees that the allocations are never returned

base/compiler/typeutils.jl

@@ -340,13 +340,29 @@ function unwraptv_lb(@nospecialize t)
 end
 const unwraptv = unwraptv_ub
 
-# this query is specially written for `adjust_effects` and returns true if a value of this type
-# never involves inconsistency of mutable objects that are allocated somewhere within a call graph
-is_consistent_argtype(@nospecialize ty) =
-    is_consistent_type(widenconst(ignorelimited(ty)))
-is_consistent_type(@nospecialize ty) = isidentityfree(ty)
+"""
+    is_identity_free_argtype(argtype) -> Bool
+
+Return `true` if the `argtype` object is identity free in the sense that this type or any
+reachable through its fields has non-content-based identity (see `Base.isidentityfree`).
+This query is specifically designed for `adjust_effects`, enabling it to refine the
+`:consistent` effect property tainted by mutable allocation(s) within the analyzed call
+graph when the return value type is `is_identity_free_argtype`, ensuring that the allocated
+mutable objects are never returned.
+"""
+is_identity_free_argtype(@nospecialize ty) = is_identity_free_type(widenconst(ignorelimited(ty)))
+is_identity_free_type(@nospecialize ty) = isidentityfree(ty)
+
+"""
+    is_immutable_argtype(argtype) -> Bool
 
-is_immutable_argtype(@nospecialize ty) = is_immutable_type(widenconst(ignorelimited(ty)))
+Return `true` if the `argtype` object is known to be immutable.
+This query is specifically designed for `getfield_effects` and `isdefined_effects`, allowing
+them to prove `:consistent`-cy of `getfield` / `isdefined` calls when applied to immutable
+objects. Otherwise, we need to additionally prove that the non-immutable object is not a
+global object to prove the `:consistent`-cy.
+"""
+is_immutable_argtype(@nospecialize argtype) = is_immutable_type(widenconst(ignorelimited(argtype)))
 is_immutable_type(@nospecialize ty) = _is_immutable_type(unwrap_unionall(ty))
 function _is_immutable_type(@nospecialize ty)
     if isa(ty, Union)
@@ -355,6 +371,16 @@ function _is_immutable_type(@nospecialize ty)
     return !isabstracttype(ty) && !ismutabletype(ty)
 end
 
-is_mutation_free_argtype(@nospecialize argtype) =
+"""
+    is_mutation_free_argtype(argtype) -> Bool
+
+Return `true` if `argtype` object is mutation free in the sense that no mutable memory
+is reachable from this type (either in the type itself) or through any fields
+(see `Base.ismutationfree`).
+This query is specifically written for analyzing the `:inaccessiblememonly` effect property
+and is supposed to improve the analysis accuracy by not tainting the `:inaccessiblememonly`
+property when there is access to mutation-free global object.
+"""
+is_mutation_free_argtype(@nospecialize(argtype)) =
     is_mutation_free_type(widenconst(ignorelimited(argtype)))
 is_mutation_free_type(@nospecialize ty) = ismutationfree(ty)