Review

Signed-off-by: Michal Maléř <mmaler@redhat.com>

docs/src/main/asciidoc/security-authorization-of-web-endpoints-reference.adoc

@@ -8,16 +8,12 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc
 include::_attributes.adoc[]
 :categories: security,web
 
-Quarkus has an integrated pluggable web security layer. If security is enabled, all HTTP requests will have a permission
-check performed to make sure they are allowed to continue.
+Quarkus has an integrated pluggable web security layer. If security is enabled, all HTTP requests will have a permission check performed to make sure they are allowed to continue.
+This means you can not use `@PermitAll` to open up a path if the path has been blocked by using the `quarkus.http.auth.` configuration.
 
 [NOTE]
 ====
-Configuration authorization checks are executed before any annotation-based authorization check is done, so both
-checks have to pass for a request to be allowed.
-This means you cannot use `@PermitAll` to open up a path if the path has been blocked by using the `quarkus.http.auth.` configuration.
-
-If you are using JAX-RS, you may want to consider using `quarkus.security.jaxrs.deny-unannotated-endpoints` or `quarkus.security.jaxrs.default-roles-allowed` to set default security requirements instead of HTTP path level matching, because annotations can override these properties on an individual endpoint.
+If you are using JAX-RS, consider using `quarkus.security.jaxrs.deny-unannotated-endpoints` or `quarkus.security.jaxrs.default-roles-allowed` to set default security requirements instead of HTTP path level matching because annotations can override these properties on an individual endpoint.
 ====
 
 Authorization is based on user roles that the security provider provides.
@@ -49,6 +45,7 @@ This is referenced by permission sets in the next snippet.
 Permission sets are defined in `application.properties` as follows:
 
 .Example of policy configuration
+[source,properties]
 ----
 quarkus.http.auth.permission.permit1.paths=/public/* <1>
 quarkus.http.auth.permission.permit1.policy=permit
@@ -139,13 +136,17 @@ quarkus.http.auth.permission.deny1.paths=/public/*
 quarkus.http.auth.permission.deny1.policy=deny
 ----
 
-TIP: Given the above permission set, `GET /public/foo` would match the paths of both permission sets, but because it matches the explicit method of the `permit1` permission set, `permit1` will be chosen, and the request will
+[NOTE]
+====
+Given the above permission set, `GET /public/foo` would match the paths of both permission sets, but because it matches the explicit method of the `permit1` permission set, `permit1` will be chosen, and the request will
 be accepted.
+
 `PUT /public/foo`, on the other hand, will not match the method permissions of `permit1`, so `deny1` will be activated and reject the request.
+====
 
 === Matching multiple paths and methods: both win
 
-If multiple permission sets specify the same path and method, or multiple has no method, then both permissions have to allow access for the request to proceed.
+When multiple permission sets win at the same time per the previously described rules, all these permissions have to allow access for the request to proceed.
 Note that for this to happen, both have to either have specified the method or have no method. Method-specific matches take precedence.
 
 [source,properties]