SEC-2532: Add disclaimer about jdbcAuthentication() with persistent data stores

config/src/main/java/org/springframework/security/config/annotation/authentication/builders/AuthenticationManagerBuilder.java

@@ -138,19 +138,31 @@ public class AuthenticationManagerBuilder extends AbstractConfiguredSecurityBuil
 
     /**
      * Add JDBC authentication to the {@link AuthenticationManagerBuilder} and
-     * return a {@link JdbcUserDetailsManagerConfigurer} to allow customization of the
-     * JDBC authentication.
+     * return a {@link JdbcUserDetailsManagerConfigurer} to allow customization
+     * of the JDBC authentication.
+     *
+     * <p>
+     * When using with a persistent data store, it is best to add users external
+     * of configuration using something like <a
+     * href="http://flywaydb.org/">Flyway</a> or <a
+     * href="http://www.liquibase.org/">Liquibase</a> to create the schema and
+     * adding users to ensure these steps are only done once and that the
+     * optimal SQL is used.
+     * </p>
      *
      * <p>
      * This method also ensure that a {@link UserDetailsService} is available
      * for the {@link #getDefaultUserDetailsService()} method. Note that
      * additional {@link UserDetailsService}'s may override this
-     * {@link UserDetailsService} as the default.
+     * {@link UserDetailsService} as the default. See the <a href=
+     * "http://docs.spring.io/spring-security/site/docs/current/reference/htmlsingle/#user-schema"
+     * >User Schema</a> section of the reference for the default schema.
      * </p>
      *
-     * @return a {@link JdbcUserDetailsManagerConfigurer} to allow customization of the
-     * JDBC authentication
-     * @throws Exception if an error occurs when adding the JDBC authentication
+     * @return a {@link JdbcUserDetailsManagerConfigurer} to allow customization
+     *         of the JDBC authentication
+     * @throws Exception
+     *             if an error occurs when adding the JDBC authentication
      */
     public JdbcUserDetailsManagerConfigurer<AuthenticationManagerBuilder> jdbcAuthentication()
             throws Exception {