Merge pull request #3670 from diesalbla/document_some_headers

Add ScalaDocs for Headers, with RFC links.

core/src/main/scala/org/http4s/headers/Accept-Charset.scala

@@ -17,6 +17,15 @@ object `Accept-Charset` extends HeaderKey.Internal[`Accept-Charset`] with Header
     HttpHeaderParser.ACCEPT_CHARSET(s)
 }
 
+/**
+  * {{{
+  *   The "Accept-Charset" header field can be sent by a user agent to
+  *   indicate what charsets are acceptable in textual response content.
+  *   This field allows user agents capable of understanding more
+  * }}}
+  *
+  * From [http//tools.ietf.org/html/rfc7231#section-5.3.3 RFC-7231].
+  */
 final case class `Accept-Charset`(values: NonEmptyList[CharsetRange])
     extends Header.RecurringRenderable {
   def key: `Accept-Charset`.type = `Accept-Charset`

core/src/main/scala/org/http4s/headers/Accept-Language.scala

@@ -15,6 +15,12 @@ object `Accept-Language` extends HeaderKey.Internal[`Accept-Language`] with Head
     HttpHeaderParser.ACCEPT_LANGUAGE(s)
 }
 
+/**
+  * Request header used to indicate which natural language would be preferred for the response
+  * to be translated into.
+  *
+  * [[https://tools.ietf.org/html/rfc7231#section-5.3.5 RFC-7231 Section 5.3.5]]
+  */
 final case class `Accept-Language`(values: NonEmptyList[LanguageTag])
     extends Header.RecurringRenderable {
   def key: `Accept-Language`.type = `Accept-Language`

core/src/main/scala/org/http4s/headers/Allow.scala

@@ -17,6 +17,12 @@ object Allow extends HeaderKey.Internal[Allow] with HeaderKey.Singleton {
     HttpHeaderParser.ALLOW(s)
 }
 
+/**
+  * A Response header that lists the methods that are supported by the target resource.
+  * Often attached to responses with status  [[https://tools.ietf.org/html/rfc7231#section-6.5.5 405 Not Allowed]].
+  *
+  * [[https://tools.ietf.org/html/rfc7231#section-7.4.1 RFC-7231 Section 7.4.1 Allow]]
+  */
 final case class Allow(methods: Set[Method]) extends Header.Parsed {
   override def key: Allow.type = Allow
   override def renderValue(writer: Writer): writer.type =

core/src/main/scala/org/http4s/headers/Content-Location.scala

@@ -15,6 +15,14 @@ object `Content-Location` extends HeaderKey.Internal[`Content-Location`] with He
     HttpHeaderParser.CONTENT_LOCATION(s)
 }
 
+/**
+  * {{{
+  *   The "Content-Location" header field references a URI that can be used
+  *   as an identifier for a specific resource corresponding to the
+  *   representation in this message's payload
+  * }}}
+  * [[https://tools.ietf.org/html/rfc7231#section-3.1.4.2 RFC-7231 Section 3.1.4.2]]
+  */
 final case class `Content-Location`(uri: Uri) extends Header.Parsed {
   def key: `Content-Location`.type = `Content-Location`
   override def value: String = uri.toString

core/src/main/scala/org/http4s/headers/Content-Type.scala

@@ -19,6 +19,16 @@ object `Content-Type` extends HeaderKey.Internal[`Content-Type`] with HeaderKey.
     HttpHeaderParser.CONTENT_TYPE(s)
 }
 
+/**
+  * {{{
+  *   The "Content-Type" header field indicates the media type of the
+  *   associated representation: either the representation enclosed in the
+  *   message payload or the selected representation, as determined by the
+  *   message semantics.
+  * }}}
+  *
+  * [[https://tools.ietf.org/html/rfc7231#section-3.1.1.5 RFC-7231]]
+  */
 final case class `Content-Type` private (mediaType: MediaType, charset: Option[Charset])
     extends Header.Parsed {
   override def key: `Content-Type`.type = `Content-Type`

core/src/main/scala/org/http4s/headers/Expect.scala

@@ -7,4 +7,7 @@
 package org.http4s
 package headers
 
+/**
+  * [[https://tools.ietf.org/html/rfc7231#section-5.1.1 RFC-7231 Section 5.1.1]]
+  */
 object Expect extends HeaderKey.Default

core/src/main/scala/org/http4s/headers/Expires.scala

@@ -16,13 +16,16 @@ object Expires extends HeaderKey.Internal[Expires] with HeaderKey.Singleton {
 }
 
 /**
-  * Constructs an `Expires` header.
+  * A Response header that _gives the date/time after which the response is considered stale_.
   *
   * The HTTP RFCs indicate that Expires should be in the range of now to 1 year in the future.
   * However, it is a usual practice to set it to the past of far in the future
   * Thus any instant is in practice allowed
   *
-  * @param expirationDate the date of expiration
+  * [[https://tools.ietf.org/html/rfc7234#section-5.3 RFC-7234 Section 5.3]]
+  *
+  * @param expirationDate the date of expiration. The RFC has a warning, that using large values
+  * can cause problems due to integer or clock overflows.
   */
 final case class Expires(expirationDate: HttpDate) extends Header.Parsed {
   val key = `Expires`

core/src/main/scala/org/http4s/headers/Host.scala

@@ -17,6 +17,19 @@ object Host extends HeaderKey.Internal[Host] with HeaderKey.Singleton {
     HttpHeaderParser.HOST(s)
 }
 
+/**
+  * A Request header, that provides the host and port informatio
+  * {{{
+  *   The "Host" header field in a request provides the host and port
+  *   information from the target URI, enabling the origin server to
+  *   distinguish among resources while servicing requests for multiple
+  *   host names on a single IP address.
+  * }}}
+  *
+  * This header was mandatory in version 1.1 of the Http protocol.
+  *
+  * [[https://tools.ietf.org/html/rfc7230#section-5.4 RFC-7230 Section 5.4]]
+  */
 final case class Host(host: String, port: Option[Int] = None) extends Header.Parsed {
   def key: Host.type = Host
   def renderValue(writer: Writer): writer.type = {

core/src/main/scala/org/http4s/headers/If-Match.scala

@@ -24,6 +24,12 @@ object `If-Match` extends HeaderKey.Internal[`If-Match`] with HeaderKey.Singleto
     HttpHeaderParser.IF_MATCH(s)
 }
 
+/**
+  * Request header to make the request conditional on the current contents of the origin server
+  * at the given target resource (URI).
+  *
+  * [[https://tools.ietf.org/html/rfc7232#section-3.1 RFC-7232 Section 3.1]]
+  */
 final case class `If-Match`(tags: Option[NonEmptyList[ETag.EntityTag]]) extends Header.Parsed {
   override def key: `If-Match`.type = `If-Match`
   override def value: String =

core/src/main/scala/org/http4s/headers/If-Modified-Since.scala

@@ -17,6 +17,15 @@ object `If-Modified-Since`
     HttpHeaderParser.IF_MODIFIED_SINCE(s)
 }
 
+/**
+  * {{
+  *   The "If-Modified-Since" header field makes a GET or HEAD request
+  *   method conditional on the selected representation's modification date
+  *   being more recent than the date provided in the field-value.
+  * }}
+  *
+  * [[https://tools.ietf.org/html/rfc7232#section-3.3 RFC-7232]]
+  */
 final case class `If-Modified-Since`(date: HttpDate) extends Header.Parsed {
   override def key: `If-Modified-Since`.type = `If-Modified-Since`
   override def value: String = Renderer.renderString(date)

core/src/main/scala/org/http4s/headers/If-None-Match.scala

@@ -12,6 +12,17 @@ import cats.syntax.foldable._
 import org.http4s.parser.HttpHeaderParser
 import org.http4s.util.Writer
 
+/**
+  * {{{
+  *  The "If-None-Match" header field makes the request method conditional
+  *  on a recipient cache or origin server either not having any current
+  *  representation of the target resource, when the field-value is "*",
+  *  or having a selected representation with an entity-tag that does not
+  *  match any of those listed in the field-value.
+  * }}}
+  *
+  * From [[https://tools.ietf.org/html/rfc7232#section-3.2 RFC-7232]]
+  */
 object `If-None-Match` extends HeaderKey.Internal[`If-None-Match`] with HeaderKey.Singleton {
 
   /** Match any existing entity */

core/src/main/scala/org/http4s/headers/If-Range.scala

@@ -7,4 +7,7 @@
 package org.http4s
 package headers
 
+/**
+  * [[https://tools.ietf.org/html/rfc7233#section-3.2 RFC-7233 Section 3.2]]
+  */
 object `If-Range` extends HeaderKey.Default

core/src/main/scala/org/http4s/headers/Last-Modified.scala

@@ -15,6 +15,12 @@ object `Last-Modified` extends HeaderKey.Internal[`Last-Modified`] with HeaderKe
     HttpHeaderParser.LAST_MODIFIED(s)
 }
 
+/**
+  * Response header that indicates the time at which the server believes the
+  * entity was last modified.
+  *
+  * [[https://tools.ietf.org/html/rfc7232#section-2.3 RFC-7232]]
+  */
 final case class `Last-Modified`(date: HttpDate) extends Header.Parsed {
   override def key: `Last-Modified`.type = `Last-Modified`
   override def value: String = Renderer.renderString(date)

core/src/main/scala/org/http4s/headers/Max-Forwards.scala

@@ -10,7 +10,13 @@ package headers
 import org.http4s.parser.HttpHeaderParser
 import org.http4s.util.Writer
 
-// see https://tools.ietf.org/html/rfc7231#section-5.1.2
+/**
+  * Request header, used with the TRACE and OPTION request methods,
+  * that gives an upper bound on how many times the request can be
+  * forwarded by a proxy before it is rejected.
+  *
+  * [[https://tools.ietf.org/html/rfc7231#section-5.1.2 RFC-7231]]
+  */
 sealed abstract case class `Max-Forwards`(count: Long) extends Header.Parsed {
   override def key: `Max-Forwards`.type = `Max-Forwards`
   override def value: String = count.toString

core/src/main/scala/org/http4s/headers/Proxy-Authenticate.scala

@@ -17,6 +17,14 @@ object `Proxy-Authenticate`
     HttpHeaderParser.PROXY_AUTHENTICATE(s)
 }
 
+/**
+  * {{{
+  *   The "Proxy-Authenticate" header field consists of at least one
+  *   challenge that indicates the authentication scheme(s) and parameters
+  *   applicable to the proxy for this effective request URI...
+  * }}}
+  * From [[https://tools.ietf.org/html/rfc7235#section-4.3 RFC-7235]]
+  */
 final case class `Proxy-Authenticate`(values: NonEmptyList[Challenge])
     extends Header.RecurringRenderable {
   override def key: `Proxy-Authenticate`.type = `Proxy-Authenticate`

core/src/main/scala/org/http4s/headers/Proxy-Authorization.scala

@@ -7,4 +7,12 @@
 package org.http4s
 package headers
 
+/**
+  * {{{
+  *   The "Proxy-Authorization" header field allows the client to identify
+  *   itself (or its user) to a proxy that requires authentication.
+  * }}}
+  *
+  *  From [[https://tools.ietf.org/html/rfc7235#section-4.4 RFC-7235]]
+  */
 object `Proxy-Authorization` extends HeaderKey.Default

core/src/main/scala/org/http4s/headers/Retry-After.scala

@@ -35,11 +35,13 @@ object `Retry-After` extends HeaderKey.Internal[`Retry-After`] with HeaderKey.Si
 }
 
 /**
-  * Constructs a `Retry-After` header.
+  * Response header, used by the server to indicate to the user-agent how long it has to wait before
+  * it can try again with a follow-up request.
   *
-  * The value of this field can be either an HTTP-date or an integer number of seconds (in decimal) after the time of the response.
+  * [[https://tools.ietf.org/html/rfc7231#section-7.1.3 RFC-7231 Section 7.1.3]]
   *
-  * @param retry Either the date of expiration or seconds until expiration
+  * @param retry Indicates the retry time, either as a date of expiration or as a number of seconds from the current time
+  * until that expiration.
   */
 sealed abstract case class `Retry-After`(retry: Either[HttpDate, Long]) extends Header.Parsed {
   val key = `Retry-After`

core/src/main/scala/org/http4s/headers/User-Agent.scala

@@ -20,7 +20,7 @@ object `User-Agent` extends HeaderKey.Internal[`User-Agent`] with HeaderKey.Sing
 
 /**
   * User-Agent header
-  * https://tools.ietf.org/html/rfc7231#section-5.5.3
+  * [[https://tools.ietf.org/html/rfc7231#section-5.5.3 RFC-7231 Section 5.5.3]]
   */
 final case class `User-Agent`(product: ProductId, rest: List[ProductIdOrComment])
     extends Header.Parsed {

core/src/main/scala/org/http4s/headers/X-Powered-By.scala

@@ -7,4 +7,11 @@
 package org.http4s
 package headers
 
+/**
+  * Non-Standard Http Header, which is often added to a Response
+  * to indicate that the response was built with a certain scripting
+  * technology, such as "ASP".
+  *
+  * https://stackoverflow.com/a/33580769/1002111
+  */
 object `X-Powered-By` extends HeaderKey.Default