Update documentation of composite provider flag. (helidon-io#6597) (helidon-io#6636)

* Update documentation of composite provider flag.

(cherry picked from commit aba7c6e)
Signed-off-by: Tomas Langer <[email protected]>

Author: tomas-langer

security/security/src/main/java/io/helidon/security/CompositeProviderFlag.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2018 Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2018, 2023 Oracle and/or its affiliates.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -27,12 +27,23 @@
 public enum CompositeProviderFlag {
     /**
      * Provider may fail, nothing happens if it does.
+     * <p>
+     * If succeeds, continues to the next provider.
+     * To create a provider that may fail, yet that is sufficient,
+     * please configure the flag to be {@link #SUFFICIENT}, and set the provider itself to be optional
+     * (most Helidon providers support {@code optional} configuration option), so the provider abstains instead of fails
+     * when user cannot be authenticated using it.
      */
     MAY_FAIL(EnumSet.of(SecurityResponse.SecurityStatus.SUCCESS,
                         SecurityResponse.SecurityStatus.ABSTAIN,
                         SecurityResponse.SecurityStatus.FAILURE)),
     /**
      * If succeeds, no further providers are called, otherwise same as optional.
+     * <p>
+     * To create a provider that may fail, yet that is sufficient,
+     * use this flag, and set the provider itself to be optional
+     * (most Helidon providers support {@code optional} configuration option), so the provider abstains instead of fails
+     * when user cannot be authenticated using it.
      */
     SUFFICIENT(EnumSet.of(SecurityResponse.SecurityStatus.SUCCESS, SecurityResponse.SecurityStatus.ABSTAIN)),
     /**