Merge pull request #240 from wgorder/SEC-3159

SEC-3159: Fix Javadoc

config/src/main/java/org/springframework/security/config/annotation/web/builders/HttpSecurity.java

@@ -219,9 +219,9 @@ public final class HttpSecurity extends
 
 	/**
 	 * Adds the Security headers to the response. This is activated by default when using
-	 * {@link WebSecurityConfigurerAdapter}'s default constructor. Only invoking the
+	 * {@link WebSecurityConfigurerAdapter}'s default constructor. Accepting the
-	 * {@link #headers()} without invoking additional methods on it, or accepting the
+	 * default provided by {@link WebSecurityConfigurerAdapter} or only invoking
-	 * default provided by {@link WebSecurityConfigurerAdapter}, is the equivalent of:
+	 * {@link #headers()} without invoking additional methods on it, is the equivalent of:
 	 *
 	 * <pre>
 	 * &#064;Configuration
@@ -232,10 +232,14 @@ public final class HttpSecurity extends
 	 *     protected void configure(HttpSecurity http) throws Exception {
 	 *         http
 	 *             .headers()
-	 *                 .contentTypeOptions();
+	 *                 .contentTypeOptions()
+	 *                 .and()
 	 *                 .xssProtection()
+	 *                 .and()
 	 *                 .cacheControl()
+	 *                 .and()
 	 *                 .httpStrictTransportSecurity()
+	 *                 .and()
 	 *                 .frameOptions()
 	 *                 .and()
 	 *             ...;
@@ -259,9 +263,10 @@ public final class HttpSecurity extends
 	 * }
 	 * </pre>
 	 *
-	 * You can enable only a few of the headers by invoking the appropriate methods on
+	 * You can enable only a few of the headers by first invoking
-	 * {@link #headers()} result. For example, the following will enable
+	 * {@link HeadersConfigurer#defaultsDisabled()}
-	 * {@link HeadersConfigurer#cacheControl()} and
+	 * and then invoking the appropriate methods on the {@link #headers()} result.
+	 * For example, the following will enable {@link HeadersConfigurer#cacheControl()} and
 	 * {@link HeadersConfigurer#frameOptions()} only.
 	 *
 	 * <pre>
@@ -273,9 +278,32 @@ public final class HttpSecurity extends
 	 *     protected void configure(HttpSecurity http) throws Exception {
 	 *         http
 	 *             .headers()
-	 *                 .cacheControl()
+	 *                  .defaultsDisabled()
-	 *                 .frameOptions()
+	 *                  .cacheControl()
-	 *                 .and()
+	 *                  .and()
+	 *                  .frameOptions()
+	 *                  .and()
+	 *             ...;
+	 *     }
+	 * }
+	 * </pre>
+	 *
+	 * You can also choose to keep the defaults but explicitly disable a subset of headers.
+	 * For example, the following will enable all the default headers except
+	 * {@link HeadersConfigurer#frameOptions()}.
+	 *
+	 * <pre>
+	 * &#064;Configuration
+	 * &#064;EnableWebSecurity
+	 * public class CsrfSecurityConfig extends WebSecurityConfigurerAdapter {
+	 *
+	 * 	&#064;Override
+	 *     protected void configure(HttpSecurity http) throws Exception {
+	 *         http
+	 *             .headers()
+	 *                  .frameOptions()
+	 *                  	.disable()
+	 *                  .and()
 	 *             ...;
 	 *     }
 	 * }