Clarification of registerServerAuthModule method.

Improved explanation in javadoc.

Signed-off-by: Arjan Tijms <arjan.tijms@gmail.com>

api/src/main/java/jakarta/security/auth/message/config/AuthConfigFactory.java

@@ -401,7 +401,24 @@ public static synchronized void setFactory(AuthConfigFactory factory) {
      *
      * <p>
      * This will override any other modules that have already been registered, either via proprietary
-     * means or using the standard API.
+     * means or using the standard API. The <code>ServerAuthModule</code> is removed, via a call to
+     * <code>removeServerAuthModule</code> when the context associated with the profile specific context object ends.
+     *
+     * <p>
+     * Note that this method is a convenience method that can be used instead of <code>registerConfigProvider</code>,
+     * but should ultimately have the same effect. That is, the <code>layer</code> and <code>appContext</code> parameters
+     * are generated from the context object, and the <code>ServerAuthModule</code> is wrapped by an implementation
+     * specific <code>AuthConfigProvider</code>, which are then used to call <code>registerConfigProvider</code> or an
+     * internal method with the same effect. The returned registration ID is then associated with the profile specific
+     * context object, and also returned from this method.
+     *
+     * <p>
+     * A "profile specific context object" is for example the <code>ServletContext</code> in the
+     * Servlet Container Profile. The context associated with this <code>ServletContext</code> ends
+     * when for example the application corresponding to it is undeployed. Association of the
+     * registration ID with the <code>ServletContext</code> simply means calling the <code>setAttribute</code>
+     * method on the <code>ServletContext</code>, with the registration ID as value. (The name attribute has not been
+     * standardised in this version of the specification)
      *
      * @param serverAuthModule the <code>ServerAuthModule</code> instance to be registered
      * @param context the profile specific context of the application for which the module is registered
@@ -423,7 +440,6 @@ public static synchronized void setFactory(AuthConfigFactory factory) {
      */
     public abstract void removeServerAuthModule(Object context);
 
-
     /**
      * Remove the identified provider registration from the factory (and from the persistent declarative representation of
      * provider registrations, if appropriate) and invoke any listeners associated with the removed registration.