Update docs on Principal controller method arguments

Closes gh-26791

Author: rstoyanchev

src/docs/asciidoc/web/webmvc.adoc

@@ -2003,6 +2003,12 @@ and others) and is equivalent to `required=false`.
 | `java.security.Principal`
 | Currently authenticated user -- possibly a specific `Principal` implementation class if known.
 
+  Note that this argument is not resolved eagerly, if it is annotated in order to allow a custom resolver to resolve it
+  before falling back on default resolution resolution via `HttpServletRequest#getUserPrincipal`.
+  For example, the Spring Security `Authentication` implements `Principal` and would be injected as such via
+  `HttpServletRequest#getUserPrincipal`, unless it is also annotated with `@AuthenticationPrincipal` in which case it
+  is resolved by a custom Spring Security resolver through `Authentication#getPrincipal`.
+
 | `HttpMethod`
 | The HTTP method of the request.