HTTPCORE-656: Improve HttpEntity.getContent() documentation (#238)
diff --git a/httpcore5/src/main/java/org/apache/hc/core5/http/HttpEntity.java b/httpcore5/src/main/java/org/apache/hc/core5/http/HttpEntity.java
index 32f6605..331aff5 100644
--- a/httpcore5/src/main/java/org/apache/hc/core5/http/HttpEntity.java
+++ b/httpcore5/src/main/java/org/apache/hc/core5/http/HttpEntity.java
@@ -85,6 +85,15 @@
* to return the same {@link InputStream} instance and therefore
* may not be consumed more than once.
* <p>
+ * If this entity belongs to an incoming HTTP message, calling
+ * {@link InputStream#close()} on the returned {@code InputStream} will
+ * try to consume the complete entity content to keep the connection
+ * alive. In cases where this is undesired, e.g. when only a small part
+ * of the content is relevant and consuming the complete entity content
+ * would be too inefficient, <i>only</i> the HTTP message from which
+ * this entity was obtained should be closed (if supported).
+ * </p>
+ * <p>
* IMPORTANT: Please note all entity implementations must ensure that
* all allocated resources are properly deallocated after
* the {@link InputStream#close()} method is invoked.
