diff --git a/org.springframework.web/src/main/java/org/springframework/http/HttpEntity.java b/org.springframework.web/src/main/java/org/springframework/http/HttpEntity.java
index f76be436e0a..edbec742481 100644
--- a/org.springframework.web/src/main/java/org/springframework/http/HttpEntity.java
+++ b/org.springframework.web/src/main/java/org/springframework/http/HttpEntity.java
@@ -23,7 +23,9 @@ import org.springframework.util.MultiValueMap;
  *
  * <p>Typically used in combination with the {@link org.springframework.web.client.RestTemplate RestTemplate}, like so:
  * <pre class="code">
- * HttpEntity&lt;String&gt; entity = new HttpEntity&lt;String&gt;(helloWorld, MediaType.TEXT_PLAIN);
+ * HttpHeaders headers = new HttpHeaders();
+ * headers.setContentType(MediaType.TEXT_PLAIN);
+ * HttpEntity&lt;String&gt; entity = new HttpEntity&lt;String&gt;(helloWorld, headers);
  * URI location = template.postForLocation("http://example.com", entity);
  * </pre>
  * or
@@ -33,12 +35,12 @@ import org.springframework.util.MultiValueMap;
  * MediaType contentType = entity.getHeaders().getContentType();
  * </pre>
  * Can also be used in Spring MVC, as a return value from a @Controller method:
- * <pre>
+ * <pre class="code">
  * &#64;RequestMapping("/handle")
- * public HttpEntity&ltString&gt handle() {
+ * public HttpEntity&lt;String&gt; handle() {
  *   HttpHeaders responseHeaders = new HttpHeaders();
  *   responseHeaders.set("MyResponseHeader", "MyValue");
- *   return new HttpEntity<String>("Hello World", responseHeaders);
+ *   return new HttpEntity&lt;String&gt;("Hello World", responseHeaders);
  * }
  * </pre>
  *
diff --git a/org.springframework.web/src/main/java/org/springframework/http/ResponseEntity.java b/org.springframework.web/src/main/java/org/springframework/http/ResponseEntity.java
index 3bbf2295df7..490cf87dca3 100644
--- a/org.springframework.web/src/main/java/org/springframework/http/ResponseEntity.java
+++ b/org.springframework.web/src/main/java/org/springframework/http/ResponseEntity.java
@@ -21,6 +21,24 @@ import org.springframework.util.MultiValueMap;
 /**
  * Extension of {@link HttpEntity} that adds a {@link HttpStatus} status code.
  *
+ * <p>Returned by {@link org.springframework.web.client.RestTemplate#getForEntity}:
+ * <pre class="code">
+ * ResponseEntity&lt;String&gt; entity = template.getForEntity("http://example.com", String.class);
+ * String body = entity.getBody();
+ * MediaType contentType = entity.getHeaders().getContentType();
+ * HttpStatus statusCode = entity.getStatusCode();
+ * </pre>
+ * Can also be used in Spring MVC, as a return value from a @Controller method:
+ * <p>Can be used in Spring MVC, as a return value from a @Controller method:
+ * <pre class="code">
+ * &#64;RequestMapping("/handle")
+ * public ResponseEntity&lt;String&gt; handle() {
+ *   HttpHeaders responseHeaders = new HttpHeaders();
+ *   responseHeaders.set("MyResponseHeader", "MyValue");
+ *   return new ResponseEntity&lt;String&gt;("Hello World", responseHeaders, HttpStatus.CREATED);
+ * }
+ * </pre>
+ *
  * @author Arjen Poutsma
  * @since 3.0.2
  * @see #getStatusCode()