diff --git a/.scalafmt.conf b/.scalafmt.conf index 90f5d54a59d..e0c6f1a32b7 100644 --- a/.scalafmt.conf +++ b/.scalafmt.conf @@ -11,4 +11,4 @@ rewrite.rules = [ AvoidInfix, ExpandImportSelectors, RedundantParens, SortModifi rewrite.sortModifiers.order = [ "private", "protected", "final", "sealed", "abstract", "implicit", "override", "lazy" ] spaces.inImportCurlyBraces = true # more idiomatic to include whitepsace in import x.{ yyy } trailingCommas = preserve -version = 2.2.2 +version = 2.3.2 diff --git a/cache/play-cache/src/main/scala/play/api/cache/AsyncCacheApi.scala b/cache/play-cache/src/main/scala/play/api/cache/AsyncCacheApi.scala index 9883a380347..cdb475fd6ff 100644 --- a/cache/play-cache/src/main/scala/play/api/cache/AsyncCacheApi.scala +++ b/cache/play-cache/src/main/scala/play/api/cache/AsyncCacheApi.scala @@ -14,6 +14,7 @@ import scala.reflect.ClassTag * The cache API */ trait AsyncCacheApi { + /** * Get an instance of [[SyncCacheApi]] to make synchronous calls. */ diff --git a/cache/play-cache/src/main/scala/play/api/cache/Cached.scala b/cache/play-cache/src/main/scala/play/api/cache/Cached.scala index 5f4e11bcc42..3c757e389a8 100644 --- a/cache/play-cache/src/main/scala/play/api/cache/Cached.scala +++ b/cache/play-cache/src/main/scala/play/api/cache/Cached.scala @@ -24,6 +24,7 @@ import scala.concurrent.duration._ * A helper to add caching to an Action. */ class Cached @Inject() (cache: AsyncCacheApi)(implicit materializer: Materializer) { + /** * Cache an action. * @@ -133,6 +134,7 @@ final class CachedBuilder( key: RequestHeader => String, caching: PartialFunction[ResponseHeader, Duration] )(implicit materializer: Materializer) { + /** * Compose the cache with an action */ diff --git a/cache/play-cache/src/main/scala/play/api/cache/SyncCacheApi.scala b/cache/play-cache/src/main/scala/play/api/cache/SyncCacheApi.scala index 7ecb934c62c..0405ff77f3e 100644 --- a/cache/play-cache/src/main/scala/play/api/cache/SyncCacheApi.scala +++ b/cache/play-cache/src/main/scala/play/api/cache/SyncCacheApi.scala @@ -16,6 +16,7 @@ import scala.reflect.ClassTag * A cache API that uses synchronous calls rather than async calls. Useful when you know you have a fast in-memory cache. */ trait SyncCacheApi { + /** * Set a value into the cache. * diff --git a/core/play-guice/src/main/scala/play/api/inject/guice/GuiceApplicationLoader.scala b/core/play-guice/src/main/scala/play/api/inject/guice/GuiceApplicationLoader.scala index 97d9395eeae..ef55ff8bf4c 100644 --- a/core/play-guice/src/main/scala/play/api/inject/guice/GuiceApplicationLoader.scala +++ b/core/play-guice/src/main/scala/play/api/inject/guice/GuiceApplicationLoader.scala @@ -43,6 +43,7 @@ class GuiceApplicationLoader(protected val initialBuilder: GuiceApplicationBuild } object GuiceApplicationLoader { + /** * The default overrides provided by the Scala and Java GuiceApplicationLoaders. */ diff --git a/core/play-guice/src/main/scala/play/api/inject/guice/GuiceInjectorBuilder.scala b/core/play-guice/src/main/scala/play/api/inject/guice/GuiceInjectorBuilder.scala index e20bf1c1c58..4304f744c11 100644 --- a/core/play-guice/src/main/scala/play/api/inject/guice/GuiceInjectorBuilder.scala +++ b/core/play-guice/src/main/scala/play/api/inject/guice/GuiceInjectorBuilder.scala @@ -424,6 +424,7 @@ object GuiceKey { * Play Injector backed by a Guice Injector. */ class GuiceInjector @Inject() (injector: com.google.inject.Injector) extends PlayInjector { + /** * Get an instance of the given class from the injector. */ diff --git a/core/play-guice/src/main/scala/play/api/libs/concurrent/ActorModule.scala b/core/play-guice/src/main/scala/play/api/libs/concurrent/ActorModule.scala index e6c39542538..549f1dc8f45 100644 --- a/core/play-guice/src/main/scala/play/api/libs/concurrent/ActorModule.scala +++ b/core/play-guice/src/main/scala/play/api/libs/concurrent/ActorModule.scala @@ -50,6 +50,7 @@ trait ActorModule extends AbstractModule { /** The companion object to hold [[ActorModule]]'s [[ActorModule.Aux]] type alias. */ @ApiMayChange object ActorModule { + /** A convenience to refer to the type of an [[ActorModule]] with the given message type [[A]]. */ type Aux[A] = ActorModule { type Message = A } } diff --git a/core/play-guice/src/main/scala/play/api/libs/concurrent/TypedAkka.scala b/core/play-guice/src/main/scala/play/api/libs/concurrent/TypedAkka.scala index 2d0b5819fb8..731b96dc3c6 100644 --- a/core/play-guice/src/main/scala/play/api/libs/concurrent/TypedAkka.scala +++ b/core/play-guice/src/main/scala/play/api/libs/concurrent/TypedAkka.scala @@ -20,6 +20,7 @@ import com.google.inject.util.Types /** Utility methods related to using Akka's typed API. */ @ApiMayChange private[play] object TypedAkka { + /** Equivalent to `new TypeLiteral[ActorRef[T]]() {}`, but with a `ClassTag[T]`. */ def actorRefOf[T: ClassTag]: TypeLiteral[ActorRef[T]] = typeLiteral(classTag[T].runtimeClass) def behaviorOf[T: ClassTag]: TypeLiteral[Behavior[T]] = typeLiteral(classTag[T].runtimeClass) diff --git a/core/play-guice/src/test/scala/play/api/inject/guice/GuiceApplicationBuilderSpec.scala b/core/play-guice/src/test/scala/play/api/inject/guice/GuiceApplicationBuilderSpec.scala index 190f8b2aebb..7fba195f1a1 100644 --- a/core/play-guice/src/test/scala/play/api/inject/guice/GuiceApplicationBuilderSpec.scala +++ b/core/play-guice/src/test/scala/play/api/inject/guice/GuiceApplicationBuilderSpec.scala @@ -90,14 +90,13 @@ class GuiceApplicationBuilderSpec extends Specification { "set module loader" in { val injector = new GuiceApplicationBuilder() - .load( - (env, conf) => - Seq( - new BuiltinModule, - new I18nModule, - new CookiesModule, - bind[GuiceApplicationBuilderSpec.A].to[GuiceApplicationBuilderSpec.A1] - ) + .load((env, conf) => + Seq( + new BuiltinModule, + new I18nModule, + new CookiesModule, + bind[GuiceApplicationBuilderSpec.A].to[GuiceApplicationBuilderSpec.A1] + ) ) .injector() diff --git a/core/play-guice/src/test/scala/play/core/test/Fakes.scala b/core/play-guice/src/test/scala/play/core/test/Fakes.scala index cef51318c46..1bb1302eb42 100644 --- a/core/play-guice/src/test/scala/play/core/test/Fakes.scala +++ b/core/play-guice/src/test/scala/play/core/test/Fakes.scala @@ -12,6 +12,7 @@ import play.api.inject.Injector * Utilities to help with testing */ object Fakes { + /** * Create an injector from the given bindings. * diff --git a/core/play-integration-test/src/it/scala/play/it/LogTester.scala b/core/play-integration-test/src/it/scala/play/it/LogTester.scala index e1794c10b82..60d152f8644 100644 --- a/core/play-integration-test/src/it/scala/play/it/LogTester.scala +++ b/core/play-integration-test/src/it/scala/play/it/LogTester.scala @@ -16,8 +16,10 @@ import scala.collection.mutable.ArrayBuffer * Test utility for testing Play logs */ object LogTester { + /** Record log events and return them for analysis. */ def recordLogEvents[T](block: => T): (T, immutable.Seq[ILoggingEvent]) = { + /** Collects all log events that occur */ class RecordingAppender extends AppenderBase[ILoggingEvent] { private val eventBuffer = ArrayBuffer[ILoggingEvent]() diff --git a/core/play-integration-test/src/it/scala/play/it/ServerIntegrationSpecification.scala b/core/play-integration-test/src/it/scala/play/it/ServerIntegrationSpecification.scala index 4c895546a0c..e4c78292c9d 100644 --- a/core/play-integration-test/src/it/scala/play/it/ServerIntegrationSpecification.scala +++ b/core/play-integration-test/src/it/scala/play/it/ServerIntegrationSpecification.scala @@ -38,6 +38,7 @@ trait ServerIntegrationSpecification extends PendingUntilFixed with AroundEach { } implicit class UntilAkkaHttpFixed[T: AsResult](t: => T) { + /** * We may want to skip some tests if they're slow due to timeouts. This tag * won't remind us if the tests start passing. @@ -49,6 +50,7 @@ trait ServerIntegrationSpecification extends PendingUntilFixed with AroundEach { } implicit class UntilNettyHttpFixed[T: AsResult](t: => T) { + /** * We may want to skip some tests if they're slow due to timeouts. This tag * won't remind us if the tests start passing. diff --git a/core/play-integration-test/src/it/scala/play/it/http/AkkaResponseHeaderHandlingSpec.scala b/core/play-integration-test/src/it/scala/play/it/http/AkkaResponseHeaderHandlingSpec.scala index dd0e996af7e..e7a32f782df 100644 --- a/core/play-integration-test/src/it/scala/play/it/http/AkkaResponseHeaderHandlingSpec.scala +++ b/core/play-integration-test/src/it/scala/play/it/http/AkkaResponseHeaderHandlingSpec.scala @@ -31,12 +31,11 @@ class AkkaResponseHeaderHandlingSpec extends PlaySpecification with AkkaHttpInte } } - "correct support invalid Authorization header" in withServer( - (Action, _) => - Action { rh => - // authorization is a invalid response header - Results.Ok.withHeaders("Authorization" -> "invalid") - } + "correct support invalid Authorization header" in withServer((Action, _) => + Action { rh => + // authorization is a invalid response header + Results.Ok.withHeaders("Authorization" -> "invalid") + } ) { port => val responses = BasicHttpClient.makeRequests(port, trickleFeed = Some(100L))( // Second request ensures that Play switches back to its normal handler @@ -47,12 +46,11 @@ class AkkaResponseHeaderHandlingSpec extends PlaySpecification with AkkaHttpInte responses(0).headers.get("Authorization") must_== Some("invalid") } - "don't strip quotes from Link header" in withServer( - (Action, _) => - Action { rh => - // Test the header reported in https://github.com/playframework/playframework/issues/7733 - Results.Ok.withHeaders("Link" -> """; rel="next"""") - } + "don't strip quotes from Link header" in withServer((Action, _) => + Action { rh => + // Test the header reported in https://github.com/playframework/playframework/issues/7733 + Results.Ok.withHeaders("Link" -> """; rel="next"""") + } ) { port => val responses = BasicHttpClient.makeRequests(port)( BasicRequest("GET", "/", "HTTP/1.1", Map(), "") @@ -62,12 +60,11 @@ class AkkaResponseHeaderHandlingSpec extends PlaySpecification with AkkaHttpInte "don't log a warning for Set-Cookie headers with negative ages" in { val problemHeaderValue = "PLAY_FLASH=; Max-Age=-86400; Expires=Tue, 30 Jan 2018 06:29:53 GMT; Path=/; HTTPOnly" - withServer( - (Action, _) => - Action { rh => - // Test the header reported in https://github.com/playframework/playframework/issues/8205 - Results.Ok.withHeaders("Set-Cookie" -> problemHeaderValue) - } + withServer((Action, _) => + Action { rh => + // Test the header reported in https://github.com/playframework/playframework/issues/8205 + Results.Ok.withHeaders("Set-Cookie" -> problemHeaderValue) + } ) { port => val (Seq(response), logMessages) = LogTester.recordLogEvents { BasicHttpClient.makeRequests(port)( diff --git a/core/play-integration-test/src/it/scala/play/it/http/BasicHttpClient.scala b/core/play-integration-test/src/it/scala/play/it/http/BasicHttpClient.scala index 500d3ed7a56..33862d39812 100644 --- a/core/play-integration-test/src/it/scala/play/it/http/BasicHttpClient.scala +++ b/core/play-integration-test/src/it/scala/play/it/http/BasicHttpClient.scala @@ -24,6 +24,7 @@ import play.core.utils.CaseInsensitiveOrdered import scala.collection.immutable.TreeMap object BasicHttpClient { + /** * Very basic HTTP client, for when we want to be very low level about our assertions. * diff --git a/core/play-integration-test/src/it/scala/play/it/http/Expect100ContinueSpec.scala b/core/play-integration-test/src/it/scala/play/it/http/Expect100ContinueSpec.scala index a30ae849364..b461773034f 100644 --- a/core/play-integration-test/src/it/scala/play/it/http/Expect100ContinueSpec.scala +++ b/core/play-integration-test/src/it/scala/play/it/http/Expect100ContinueSpec.scala @@ -41,8 +41,8 @@ trait Expect100ContinueSpec extends PlaySpecification with ServerIntegrationSpec responses(1).status must_== 200 } - "not read body when expecting 100 continue but action iteratee is done" in withServer( - _ => EssentialAction(_ => Accumulator.done(Results.Ok)) + "not read body when expecting 100 continue but action iteratee is done" in withServer(_ => + EssentialAction(_ => Accumulator.done(Results.Ok)) ) { port => val responses = BasicHttpClient.makeRequests(port)( BasicRequest("POST", "/", "HTTP/1.1", Map("Expect" -> "100-continue", "Content-Length" -> "100000"), "foo") @@ -58,8 +58,8 @@ trait Expect100ContinueSpec extends PlaySpecification with ServerIntegrationSpec // close the connection. // // See https://issues.jboss.org/browse/NETTY-390 for more details. - "close the connection after rejecting a Expect: 100-continue body" in withServer( - _ => EssentialAction(_ => Accumulator.done(Results.Ok)) + "close the connection after rejecting a Expect: 100-continue body" in withServer(_ => + EssentialAction(_ => Accumulator.done(Results.Ok)) ) { port => val responses = BasicHttpClient.makeRequests(port, checkClosed = true)( BasicRequest("POST", "/", "HTTP/1.1", Map("Expect" -> "100-continue", "Content-Length" -> "100000"), "foo") diff --git a/core/play-integration-test/src/it/scala/play/it/http/FlashCookieSpec.scala b/core/play-integration-test/src/it/scala/play/it/http/FlashCookieSpec.scala index f3b171573bd..4be7fe05c98 100644 --- a/core/play-integration-test/src/it/scala/play/it/http/FlashCookieSpec.scala +++ b/core/play-integration-test/src/it/scala/play/it/http/FlashCookieSpec.scala @@ -25,6 +25,7 @@ class FlashCookieSpec with EndpointIntegrationSpecification with OkHttpEndpointSupport with ApplicationFactories { + /** Makes an app that we use while we're testing */ def withFlashCookieApp(additionalConfiguration: Map[String, Any] = Map.empty): ApplicationFactory = { withConfigAndRouter(additionalConfiguration) { components => diff --git a/core/play-integration-test/src/it/scala/play/it/http/JavaResultsHandlingSpec.scala b/core/play-integration-test/src/it/scala/play/it/http/JavaResultsHandlingSpec.scala index bad50e8b924..ae643e972b8 100644 --- a/core/play-integration-test/src/it/scala/play/it/http/JavaResultsHandlingSpec.scala +++ b/core/play-integration-test/src/it/scala/play/it/http/JavaResultsHandlingSpec.scala @@ -246,8 +246,8 @@ trait JavaResultsHandlingSpec Results.ok("Hello world").discardingCookie("Result-Discard") } }) { response => - response.headers("Set-Cookie") must contain( - (s: String) => s.startsWith("Result-Discard=; Max-Age=0; Expires=Thu, 01 Jan 1970 00:00:00 GMT; Path=/") + response.headers("Set-Cookie") must contain((s: String) => + s.startsWith("Result-Discard=; Max-Age=0; Expires=Thu, 01 Jan 1970 00:00:00 GMT; Path=/") ) } @@ -256,8 +256,8 @@ trait JavaResultsHandlingSpec Results.ok("Hello world").discardingCookie("Result-Discard", "/path") } }) { response => - response.headers("Set-Cookie") must contain( - (s: String) => s.startsWith("Result-Discard=; Max-Age=0; Expires=Thu, 01 Jan 1970 00:00:00 GMT; Path=/path") + response.headers("Set-Cookie") must contain((s: String) => + s.startsWith("Result-Discard=; Max-Age=0; Expires=Thu, 01 Jan 1970 00:00:00 GMT; Path=/path") ) } @@ -266,11 +266,10 @@ trait JavaResultsHandlingSpec Results.ok("Hello world").discardingCookie("Result-Discard", "/path", "playframework.com") } }) { response => - response.headers("Set-Cookie") must contain( - (s: String) => - s.startsWith( - "Result-Discard=; Max-Age=0; Expires=Thu, 01 Jan 1970 00:00:00 GMT; Path=/path; Domain=playframework.com" - ) + response.headers("Set-Cookie") must contain((s: String) => + s.startsWith( + "Result-Discard=; Max-Age=0; Expires=Thu, 01 Jan 1970 00:00:00 GMT; Path=/path; Domain=playframework.com" + ) ) } @@ -279,11 +278,10 @@ trait JavaResultsHandlingSpec Results.ok("Hello world").discardingCookie("Result-Discard", "/path", "playframework.com", true) } }) { response => - response.headers("Set-Cookie") must contain( - (s: String) => - s.startsWith( - "Result-Discard=; Max-Age=0; Expires=Thu, 01 Jan 1970 00:00:00 GMT; Path=/path; Domain=playframework.com; Secure" - ) + response.headers("Set-Cookie") must contain((s: String) => + s.startsWith( + "Result-Discard=; Max-Age=0; Expires=Thu, 01 Jan 1970 00:00:00 GMT; Path=/path; Domain=playframework.com; Secure" + ) ) } } @@ -327,8 +325,8 @@ trait JavaResultsHandlingSpec } } } { response => - response.headers("Set-Cookie") must contain( - (s: String) => s.equalsIgnoreCase("PLAY_LANG=pt-BR; SameSite=Lax; Path=/") + response.headers("Set-Cookie") must contain((s: String) => + s.equalsIgnoreCase("PLAY_LANG=pt-BR; SameSite=Lax; Path=/") ) } @@ -340,8 +338,8 @@ trait JavaResultsHandlingSpec } } } { response => - response.headers("Set-Cookie") must contain( - (s: String) => s.equalsIgnoreCase("PLAY_LANG=pt-BR; SameSite=Lax; Path=/") + response.headers("Set-Cookie") must contain((s: String) => + s.equalsIgnoreCase("PLAY_LANG=pt-BR; SameSite=Lax; Path=/") ) } @@ -353,8 +351,8 @@ trait JavaResultsHandlingSpec } } } { response => - response.headers("Set-Cookie") must contain( - (s: String) => s.equalsIgnoreCase("PLAY_LANG=pt-BR; SameSite=Lax; Path=/") + response.headers("Set-Cookie") must contain((s: String) => + s.equalsIgnoreCase("PLAY_LANG=pt-BR; SameSite=Lax; Path=/") ) } @@ -370,8 +368,8 @@ trait JavaResultsHandlingSpec } } } { response => - response.headers("Set-Cookie") must contain( - (s: String) => s.equalsIgnoreCase("LANG_TEST_COOKIE=pt-BR; SameSite=Lax; Path=/") + response.headers("Set-Cookie") must contain((s: String) => + s.equalsIgnoreCase("LANG_TEST_COOKIE=pt-BR; SameSite=Lax; Path=/") ) } @@ -405,8 +403,8 @@ trait JavaResultsHandlingSpec } } } { response => - response.headers("Set-Cookie") must contain( - (s: String) => s.equalsIgnoreCase("PLAY_LANG=pt-BR; SameSite=Lax; Path=/; Secure") + response.headers("Set-Cookie") must contain((s: String) => + s.equalsIgnoreCase("PLAY_LANG=pt-BR; SameSite=Lax; Path=/; Secure") ) } @@ -422,8 +420,8 @@ trait JavaResultsHandlingSpec } } } { response => - response.headers("Set-Cookie") must contain( - (s: String) => s.equalsIgnoreCase("PLAY_LANG=pt-BR; SameSite=Lax; Path=/; HttpOnly") + response.headers("Set-Cookie") must contain((s: String) => + s.equalsIgnoreCase("PLAY_LANG=pt-BR; SameSite=Lax; Path=/; HttpOnly") ) } } @@ -438,8 +436,8 @@ trait JavaResultsHandlingSpec } } } { response => - response.headers("Set-Cookie") must contain( - (s: String) => s.equalsIgnoreCase("PLAY_LANG=; Max-Age=0; Expires=Thu, 01 Jan 1970 00:00:00 GMT; Path=/") + response.headers("Set-Cookie") must contain((s: String) => + s.equalsIgnoreCase("PLAY_LANG=; Max-Age=0; Expires=Thu, 01 Jan 1970 00:00:00 GMT; Path=/") ) } @@ -451,8 +449,8 @@ trait JavaResultsHandlingSpec } } } { response => - response.headers("Set-Cookie") must contain( - (s: String) => s.equalsIgnoreCase("PLAY_LANG=; Max-Age=0; Expires=Thu, 01 Jan 1970 00:00:00 GMT; Path=/") + response.headers("Set-Cookie") must contain((s: String) => + s.equalsIgnoreCase("PLAY_LANG=; Max-Age=0; Expires=Thu, 01 Jan 1970 00:00:00 GMT; Path=/") ) } } diff --git a/core/play-integration-test/src/it/scala/play/it/http/RequestBodyHandlingSpec.scala b/core/play-integration-test/src/it/scala/play/it/http/RequestBodyHandlingSpec.scala index 90f91c0074d..e6b4808a267 100644 --- a/core/play-integration-test/src/it/scala/play/it/http/RequestBodyHandlingSpec.scala +++ b/core/play-integration-test/src/it/scala/play/it/http/RequestBodyHandlingSpec.scala @@ -58,11 +58,10 @@ trait RequestBodyHandlingSpec extends PlaySpecification with ServerIntegrationSp withServerAndConfig()(action)(block) } - "handle gzip bodies" in withServer( - (Action, _) => - Action { rh => - Results.Ok(rh.body.asText.getOrElse("")) - } + "handle gzip bodies" in withServer((Action, _) => + Action { rh => + Results.Ok(rh.body.asText.getOrElse("")) + } ) { port => val bodyString = "Hello World" @@ -86,11 +85,10 @@ trait RequestBodyHandlingSpec extends PlaySpecification with ServerIntegrationSp response.body.left.get must_== bodyString } - "handle large bodies" in withServer( - (_, _) => - EssentialAction { rh => - Accumulator(Sink.ignore).map(_ => Results.Ok) - } + "handle large bodies" in withServer((_, _) => + EssentialAction { rh => + Accumulator(Sink.ignore).map(_ => Results.Ok) + } ) { port => val body = new String(Random.alphanumeric.take(50 * 1024).toArray) val responses = BasicHttpClient.makeRequests(port, trickleFeed = Some(100L))( @@ -103,11 +101,10 @@ trait RequestBodyHandlingSpec extends PlaySpecification with ServerIntegrationSp responses(1).status must_== 200 } - "gracefully handle early body parser termination" in withServer( - (_, _) => - EssentialAction { rh => - Accumulator(Sink.ignore).through(Flow[ByteString].take(10)).map(_ => Results.Ok) - } + "gracefully handle early body parser termination" in withServer((_, _) => + EssentialAction { rh => + Accumulator(Sink.ignore).through(Flow[ByteString].take(10)).map(_ => Results.Ok) + } ) { port => val body = new String(Random.alphanumeric.take(50 * 1024).toArray) // Trickle feed is important, otherwise it won't switch to ignoring the body. @@ -121,11 +118,10 @@ trait RequestBodyHandlingSpec extends PlaySpecification with ServerIntegrationSp responses(1).status must_== 200 } - "handle a big http request" in withServer( - (Action, parse) => - Action(parse.default(Some(Long.MaxValue))) { rh => - Results.Ok(rh.body.asText.getOrElse("")) - } + "handle a big http request" in withServer((Action, parse) => + Action(parse.default(Some(Long.MaxValue))) { rh => + Results.Ok(rh.body.asText.getOrElse("")) + } ) { port => // big body that should not crash akka and netty val body = "Hello World" * (1024 * 1024) @@ -138,11 +134,10 @@ trait RequestBodyHandlingSpec extends PlaySpecification with ServerIntegrationSp "handle a big http request and fail with HTTP Error '413 request entity too large'" in withServerAndConfig( "play.server.max-content-length" -> "21b" - )( - (Action, parse) => - Action(parse.default(Some(Long.MaxValue))) { rh => - Results.Ok(rh.body.asText.getOrElse("")) - } + )((Action, parse) => + Action(parse.default(Some(Long.MaxValue))) { rh => + Results.Ok(rh.body.asText.getOrElse("")) + } ) { port => val body = "Hello World" * 2 // => 22 bytes, but we allow only 21 bytes val responses = BasicHttpClient.makeRequests(port, trickleFeed = Some(100L))( @@ -154,11 +149,10 @@ trait RequestBodyHandlingSpec extends PlaySpecification with ServerIntegrationSp "handle a big http request with exact amount of allowed Content-Length" in withServerAndConfig( "play.server.max-content-length" -> "22b" - )( - (Action, parse) => - Action(parse.default(Some(Long.MaxValue))) { rh => - Results.Ok(rh.body.asText.getOrElse("")) - } + )((Action, parse) => + Action(parse.default(Some(Long.MaxValue))) { rh => + Results.Ok(rh.body.asText.getOrElse("")) + } ) { port => val body = "Hello World" * 2 // => 22 bytes, same what we allow val responses = BasicHttpClient.makeRequests(port, trickleFeed = Some(100L))( diff --git a/core/play-integration-test/src/it/scala/play/it/http/RequestHeadersSpec.scala b/core/play-integration-test/src/it/scala/play/it/http/RequestHeadersSpec.scala index 36a09f9a327..8299e193e20 100644 --- a/core/play-integration-test/src/it/scala/play/it/http/RequestHeadersSpec.scala +++ b/core/play-integration-test/src/it/scala/play/it/http/RequestHeadersSpec.scala @@ -26,11 +26,10 @@ class AkkaHttpRequestHeadersSpec extends RequestHeadersSpec with AkkaHttpIntegra // to fail. I think it's still worth including this test because it // will still often report correct failures, even if it's not perfect. - withServerAndConfig()( - (Action, _) => - Action { rh => - Results.Ok(rh.headers.get("User-Agent").toString) - } + withServerAndConfig()((Action, _) => + Action { rh => + Results.Ok(rh.headers.get("User-Agent").toString) + } ) { port => def testAgent(agent: String) = { val (_, logMessages) = LogTester.recordLogEvents { @@ -100,11 +99,10 @@ trait RequestHeadersSpec extends PlaySpecification with ServerIntegrationSpecifi } "Play request header handling" should { - "get request headers properly" in withServer( - (Action, _) => - Action { rh => - Results.Ok(rh.headers.getAll("Origin").mkString(",")) - } + "get request headers properly" in withServer((Action, _) => + Action { rh => + Results.Ok(rh.headers.getAll("Origin").mkString(",")) + } ) { port => val Seq(response) = BasicHttpClient.makeRequests(port)( BasicRequest("GET", "/", "HTTP/1.1", Map("origin" -> "http://foo"), "") @@ -112,11 +110,10 @@ trait RequestHeadersSpec extends PlaySpecification with ServerIntegrationSpecifi response.body.left.toOption must beSome("http://foo") } - "remove request headers properly" in withServer( - (Action, _) => - Action { rh => - Results.Ok(rh.headers.remove("ORIGIN").getAll("Origin").mkString(",")) - } + "remove request headers properly" in withServer((Action, _) => + Action { rh => + Results.Ok(rh.headers.remove("ORIGIN").getAll("Origin").mkString(",")) + } ) { port => val Seq(response) = BasicHttpClient.makeRequests(port)( BasicRequest("GET", "/", "HTTP/1.1", Map("origin" -> "http://foo"), "") @@ -124,11 +121,10 @@ trait RequestHeadersSpec extends PlaySpecification with ServerIntegrationSpecifi response.body.left.toOption must beSome("") } - "replace request headers properly" in withServer( - (Action, _) => - Action { rh => - Results.Ok(rh.headers.replace("Origin" -> "https://bar.com").getAll("Origin").mkString(",")) - } + "replace request headers properly" in withServer((Action, _) => + Action { rh => + Results.Ok(rh.headers.replace("Origin" -> "https://bar.com").getAll("Origin").mkString(",")) + } ) { port => val Seq(response) = BasicHttpClient.makeRequests(port)( BasicRequest("GET", "/", "HTTP/1.1", Map("origin" -> "http://foo"), "") @@ -136,12 +132,11 @@ trait RequestHeadersSpec extends PlaySpecification with ServerIntegrationSpecifi response.body.left.toOption must beSome("https://bar.com") } - "not expose a content-type when there's no body" in withServer( - (Action, _) => - Action { rh => - // the body is a String representation of `get("Content-Type")` - Results.Ok(rh.headers.get("Content-Type").getOrElse("no-header")) - } + "not expose a content-type when there's no body" in withServer((Action, _) => + Action { rh => + // the body is a String representation of `get("Content-Type")` + Results.Ok(rh.headers.get("Content-Type").getOrElse("no-header")) + } ) { port => val Seq(response) = BasicHttpClient.makeRequests(port)( // an empty body implies no parsing is used and no content type is derived from the body. @@ -150,12 +145,11 @@ trait RequestHeadersSpec extends PlaySpecification with ServerIntegrationSpecifi response.body.left.toOption must beSome("no-header") } - "pass common tests for headers" in withServer( - (Action, _) => - Action { rh => - commonTests(rh.headers) - Results.Ok("Done") - } + "pass common tests for headers" in withServer((Action, _) => + Action { rh => + commonTests(rh.headers) + Results.Ok("Done") + } ) { port => val Seq(response) = BasicHttpClient.makeRequests(port)( BasicRequest( @@ -170,17 +164,16 @@ trait RequestHeadersSpec extends PlaySpecification with ServerIntegrationSpecifi } "get request headers properly when Content-Encoding is set" in { - withServer( - (Action, _) => - Action { rh => - Results.Ok( - Seq("Content-Encoding", "Authorization", "X-Custom-Header") - .map { headerName => - s"$headerName -> ${rh.headers.get(headerName)}" - } - .mkString(", ") - ) - } + withServer((Action, _) => + Action { rh => + Results.Ok( + Seq("Content-Encoding", "Authorization", "X-Custom-Header") + .map { headerName => + s"$headerName -> ${rh.headers.get(headerName)}" + } + .mkString(", ") + ) + } ) { port => val Seq(response) = BasicHttpClient.makeRequests(port)( BasicRequest( @@ -205,11 +198,10 @@ trait RequestHeadersSpec extends PlaySpecification with ServerIntegrationSpecifi "preserve the value of headers" in { def headerValueInRequest(headerName: String, headerValue: String): MatchResult[Either[String, _]] = { - withServer( - (Action, _) => - Action { rh => - Results.Ok(rh.headers.get(headerName).toString) - } + withServer((Action, _) => + Action { rh => + Results.Ok(rh.headers.get(headerName).toString) + } ) { port => val Seq(response) = BasicHttpClient.makeRequests(port)( // an empty body implies no parsing is used and no content type is derived from the body. @@ -232,11 +224,10 @@ trait RequestHeadersSpec extends PlaySpecification with ServerIntegrationSpecifi "preserve the case of header names" in { def headerNameInRequest(headerName: String, headerValue: String): MatchResult[Either[String, _]] = { - withServer( - (Action, _) => - Action { rh => - Results.Ok(rh.headers.keys.filter(_.equalsIgnoreCase(headerName)).mkString) - } + withServer((Action, _) => + Action { rh => + Results.Ok(rh.headers.keys.filter(_.equalsIgnoreCase(headerName)).mkString) + } ) { port => val Seq(response) = BasicHttpClient.makeRequests(port)( // an empty body implies no parsing is used and no content type is derived from the body. @@ -282,11 +273,10 @@ trait RequestHeadersSpec extends PlaySpecification with ServerIntegrationSpecifi "maintain uri and path consistency" in { def uriInRequest(uri: String): MatchResult[Either[String, _]] = { - withServer( - (Action, _) => - Action { rh => - Results.Ok((rh.uri.contains(rh.path) && rh.uri.contains(rh.rawQueryString)).toString) - } + withServer((Action, _) => + Action { rh => + Results.Ok((rh.uri.contains(rh.path) && rh.uri.contains(rh.rawQueryString)).toString) + } ) { port => val Seq(response) = BasicHttpClient.makeRequests(port)( BasicRequest("GET", uri, "HTTP/1.1", Map(), "") diff --git a/core/play-integration-test/src/it/scala/play/it/http/SecureFlagSpec.scala b/core/play-integration-test/src/it/scala/play/it/http/SecureFlagSpec.scala index cbc047d301e..3a8614186a0 100644 --- a/core/play-integration-test/src/it/scala/play/it/http/SecureFlagSpec.scala +++ b/core/play-integration-test/src/it/scala/play/it/http/SecureFlagSpec.scala @@ -17,6 +17,7 @@ class SecureFlagSpec with EndpointIntegrationSpecification with OkHttpEndpointSupport with ApplicationFactories { + /** An ApplicationFactory with a single action that returns the request's `secure` flag. */ val secureFlagAppFactory: ApplicationFactory = withAction { actionBuilder => actionBuilder { request: Request[_] => diff --git a/core/play-integration-test/src/it/scala/play/it/http/websocket/WebSocketClient.scala b/core/play-integration-test/src/it/scala/play/it/http/websocket/WebSocketClient.scala index b088715fcae..1005bd0a02c 100644 --- a/core/play-integration-test/src/it/scala/play/it/http/websocket/WebSocketClient.scala +++ b/core/play-integration-test/src/it/scala/play/it/http/websocket/WebSocketClient.scala @@ -45,6 +45,7 @@ import scala.language.implicitConversions * more Scala friendly. */ trait WebSocketClient { + /** * Connect to the given URI * diff --git a/core/play-integration-test/src/it/scala/play/it/http/websocket/WebSocketSpec.scala b/core/play-integration-test/src/it/scala/play/it/http/websocket/WebSocketSpec.scala index 9edbccb240b..f69392f2268 100644 --- a/core/play-integration-test/src/it/scala/play/it/http/websocket/WebSocketSpec.scala +++ b/core/play-integration-test/src/it/scala/play/it/http/websocket/WebSocketSpec.scala @@ -52,11 +52,10 @@ trait PingWebSocketSpec sequential "respond to pings" in { - withServer( - app => - WebSocket.accept[String, String] { req => - Flow.fromSinkAndSource(Sink.ignore, Source.maybe[String]) - } + withServer(app => + WebSocket.accept[String, String] { req => + Flow.fromSinkAndSource(Sink.ignore, Source.maybe[String]) + } ) { app => import app.materializer val frames = runWebSocket { flow => @@ -75,11 +74,10 @@ trait PingWebSocketSpec } "not respond to pongs" in { - withServer( - app => - WebSocket.accept[String, String] { req => - Flow.fromSinkAndSource(Sink.ignore, Source.maybe[String]) - } + withServer(app => + WebSocket.accept[String, String] { req => + Flow.fromSinkAndSource(Sink.ignore, Source.maybe[String]) + } ) { app => import app.materializer val frames = runWebSocket { flow => @@ -147,11 +145,10 @@ trait WebSocketSpec "aggregate text frames" in { val consumed = Promise[List[String]]() - withServer( - app => - WebSocket.accept[String, String] { req => - Flow.fromSinkAndSource(onFramesConsumed[String](consumed.success(_)), Source.maybe[String]) - } + withServer(app => + WebSocket.accept[String, String] { req => + Flow.fromSinkAndSource(onFramesConsumed[String](consumed.success(_)), Source.maybe[String]) + } ) { app => import app.materializer val result = runWebSocket { flow => @@ -172,11 +169,10 @@ trait WebSocketSpec "aggregate binary frames" in { val consumed = Promise[List[ByteString]]() - withServer( - app => - WebSocket.accept[ByteString, ByteString] { req => - Flow.fromSinkAndSource(onFramesConsumed[ByteString](consumed.success(_)), Source.maybe[ByteString]) - } + withServer(app => + WebSocket.accept[ByteString, ByteString] { req => + Flow.fromSinkAndSource(onFramesConsumed[ByteString](consumed.success(_)), Source.maybe[ByteString]) + } ) { app => import app.materializer val result = runWebSocket { flow => @@ -195,11 +191,10 @@ trait WebSocketSpec } "close the websocket when the buffer limit is exceeded" in { - withServer( - app => - WebSocket.accept[String, String] { req => - Flow.fromSinkAndSource(Sink.ignore, Source.maybe[String]) - } + withServer(app => + WebSocket.accept[String, String] { req => + Flow.fromSinkAndSource(Sink.ignore, Source.maybe[String]) + } ) { app => import app.materializer val frames = runWebSocket { flow => @@ -217,11 +212,10 @@ trait WebSocketSpec } "select one of the subprotocols proposed by the client" in { - withServer( - app => - WebSocket.accept[String, String] { req => - Flow.fromSinkAndSource(Sink.ignore, Source(Nil)) - } + withServer(app => + WebSocket.accept[String, String] { req => + Flow.fromSinkAndSource(Sink.ignore, Source(Nil)) + } ) { app => import app.materializer val (_, headers) = runWebSocket({ flow => @@ -237,11 +231,10 @@ trait WebSocketSpec // we keep getting timeouts on this test // java.util.concurrent.TimeoutException: Futures timed out after [5 seconds] (Helpers.scala:186) "close the websocket when the wrong type of frame is received" in { - withServer( - app => - WebSocket.accept[String, String] { req => - Flow.fromSinkAndSource(Sink.ignore, Source.maybe[String]) - } + withServer(app => + WebSocket.accept[String, String] { req => + Flow.fromSinkAndSource(Sink.ignore, Source.maybe[String]) + } ) { app => import app.materializer val frames = runWebSocket { flow => diff --git a/core/play-integration-test/src/it/scala/play/it/server/ServerReloadingSpec.scala b/core/play-integration-test/src/it/scala/play/it/server/ServerReloadingSpec.scala index 55b09d21fd0..c9732c49ab8 100644 --- a/core/play-integration-test/src/it/scala/play/it/server/ServerReloadingSpec.scala +++ b/core/play-integration-test/src/it/scala/play/it/server/ServerReloadingSpec.scala @@ -243,6 +243,7 @@ trait ServerReloadingSpec extends PlaySpecification with WsTestClient with Serve } private[server] object ServerReloadingSpec { + /** * The router for an application to help test server reloading. */ diff --git a/core/play-integration-test/src/it/scala/play/it/test/EndpointIntegrationSpecification.scala b/core/play-integration-test/src/it/scala/play/it/test/EndpointIntegrationSpecification.scala index 297447973fa..46b9887c8c3 100644 --- a/core/play-integration-test/src/it/scala/play/it/test/EndpointIntegrationSpecification.scala +++ b/core/play-integration-test/src/it/scala/play/it/test/EndpointIntegrationSpecification.scala @@ -23,10 +23,12 @@ import play.core.server.ServerEndpoint * @see [[ServerEndpoint]] */ trait EndpointIntegrationSpecification extends SpecLike with PendingUntilFixed with ApplicationFactories { + /** * Implicit class that enhances [[ApplicationFactory]] with the [[withAllEndpoints()]] method. */ implicit class ApplicationFactoryEndpointBaker(val appFactory: ApplicationFactory) { + /** * Helper that creates a specs2 fragment for the given server endpoints. * Each fragment creates an application, starts a server @@ -67,6 +69,7 @@ trait EndpointIntegrationSpecification extends SpecLike with PendingUntilFixed w * Implicit class that enhances code blocks with some `pendingUntilFixed`-style methods. */ implicit class EndpointsPendingUntilFixed[T: AsResult](block: => T) { + /** * Same as `pendingUntilFixed`, but only if a condition is met. * Otherwise the test executes as normal. diff --git a/core/play-integration-test/src/it/scala/play/it/test/OkHttpEndpointSupport.scala b/core/play-integration-test/src/it/scala/play/it/test/OkHttpEndpointSupport.scala index f492e95528e..46c2a00aa0f 100644 --- a/core/play-integration-test/src/it/scala/play/it/test/OkHttpEndpointSupport.scala +++ b/core/play-integration-test/src/it/scala/play/it/test/OkHttpEndpointSupport.scala @@ -26,6 +26,7 @@ trait OkHttpEndpointSupport { /** Describes an [[OkHttpClient] that is bound to a particular [[ServerEndpoint]]. */ trait OkHttpEndpoint { + /** The endpoint to connect to. */ def endpoint: ServerEndpoint @@ -86,6 +87,7 @@ trait OkHttpEndpointSupport { * Implicit class that enhances [[ApplicationFactory]] with the [[withAllOkHttpEndpoints()]] method. */ implicit class OkHttpApplicationFactory(appFactory: ApplicationFactory) { + /** * Helper that creates a specs2 fragment for the given server endpoints. * Each fragment creates an application, starts a server, diff --git a/core/play-integration-test/src/it/scala/play/it/test/WSEndpointSupport.scala b/core/play-integration-test/src/it/scala/play/it/test/WSEndpointSupport.scala index 09131b41fea..d0890e59662 100644 --- a/core/play-integration-test/src/it/scala/play/it/test/WSEndpointSupport.scala +++ b/core/play-integration-test/src/it/scala/play/it/test/WSEndpointSupport.scala @@ -42,6 +42,7 @@ trait WSEndpointSupport { /** Describes a [[WSClient]] that is bound to a particular [[ServerEndpoint]]. */ @implicitNotFound("Use withAllWSEndpoints { implicit wsEndpoint: WSEndpoint => ... } to get a value") trait WSEndpoint { + /** The endpoint to connect to. */ def endpoint: ServerEndpoint @@ -108,6 +109,7 @@ trait WSEndpointSupport { * Implicit class that enhances [[ApplicationFactory]] with the [[withAllWSEndpoints()]] method. */ implicit class WSApplicationFactory(appFactory: ApplicationFactory) { + /** * Helper that creates a specs2 fragment for the server endpoints given in * [[allEndpointRecipes]]. Each fragment creates an application, starts a server, diff --git a/core/play-microbenchmark/src/test/scala/play/microbenchmark/it/HelloWorldBenchmark.scala b/core/play-microbenchmark/src/test/scala/play/microbenchmark/it/HelloWorldBenchmark.scala index cb53e1ff927..5106698ec6b 100644 --- a/core/play-microbenchmark/src/test/scala/play/microbenchmark/it/HelloWorldBenchmark.scala +++ b/core/play-microbenchmark/src/test/scala/play/microbenchmark/it/HelloWorldBenchmark.scala @@ -30,6 +30,7 @@ import scala.util.Random @Threads(64) @State(Scope.Benchmark) class HelloWorldBenchmark { + /** Which type of backend and connection to use. */ @Param(Array("nt-11-pln", "nt-11-enc", "ak-11-pln", "ak-11-enc", "ak-20-enc")) var endpoint: String = null @@ -71,6 +72,7 @@ class HelloWorldBenchmark { } object HelloWorldBenchmark { + /** * Contains state used by each thread in the benchmark. Each thread * has its own HTTP client. This means there's less contention between @@ -80,6 +82,7 @@ object HelloWorldBenchmark { */ @State(Scope.Thread) class ThreadState { + /** Used to make requests. */ private var client: OkHttpClient = null diff --git a/core/play-streams/src/main/scala/play/api/libs/streams/Accumulator.scala b/core/play-streams/src/main/scala/play/api/libs/streams/Accumulator.scala index c6d7f6959af..7f16ad35597 100644 --- a/core/play-streams/src/main/scala/play/api/libs/streams/Accumulator.scala +++ b/core/play-streams/src/main/scala/play/api/libs/streams/Accumulator.scala @@ -29,6 +29,7 @@ import scala.compat.java8.OptionConverters._ * methods for working directly with that future as well as transforming the input. */ sealed trait Accumulator[-E, +A] { + /** * Map the result of this accumulator to something else. */ diff --git a/core/play-streams/src/main/scala/play/api/libs/streams/ActorFlow.scala b/core/play-streams/src/main/scala/play/api/libs/streams/ActorFlow.scala index ca4ed8dbe88..f40df3cc272 100644 --- a/core/play-streams/src/main/scala/play/api/libs/streams/ActorFlow.scala +++ b/core/play-streams/src/main/scala/play/api/libs/streams/ActorFlow.scala @@ -18,6 +18,7 @@ import akka.stream.scaladsl.Flow * See https://github.com/akka/akka/issues/16985. */ object ActorFlow { + /** * Create a flow that is handled by an actor. * diff --git a/core/play-streams/src/main/scala/play/api/libs/streams/AkkaStreams.scala b/core/play-streams/src/main/scala/play/api/libs/streams/AkkaStreams.scala index 18f8a4251a2..61b4f0cc105 100644 --- a/core/play-streams/src/main/scala/play/api/libs/streams/AkkaStreams.scala +++ b/core/play-streams/src/main/scala/play/api/libs/streams/AkkaStreams.scala @@ -15,6 +15,7 @@ import scala.concurrent.Future * Utilities for Akka Streams merging and bypassing of packets. */ object AkkaStreams { + /** * Bypass the given flow using the given splitter function. * diff --git a/core/play-streams/src/main/scala/play/api/libs/streams/GzipFlow.scala b/core/play-streams/src/main/scala/play/api/libs/streams/GzipFlow.scala index f2ab5054762..4324a9671a7 100644 --- a/core/play-streams/src/main/scala/play/api/libs/streams/GzipFlow.scala +++ b/core/play-streams/src/main/scala/play/api/libs/streams/GzipFlow.scala @@ -18,6 +18,7 @@ import akka.util.ByteString * GZIPs each chunk separately. */ object GzipFlow { + /** * Create a Gzip Flow with the given buffer size. */ diff --git a/core/play-streams/src/test/scala/play/api/libs/streams/AccumulatorSpec.scala b/core/play-streams/src/test/scala/play/api/libs/streams/AccumulatorSpec.scala index 4221853e9f3..c3a5f350e8f 100644 --- a/core/play-streams/src/test/scala/play/api/libs/streams/AccumulatorSpec.scala +++ b/core/play-streams/src/test/scala/play/api/libs/streams/AccumulatorSpec.scala @@ -35,12 +35,11 @@ class AccumulatorSpec extends Specification { def await[T](f: Future[T]): T = Await.result(f, 10.seconds) def error[T](any: Any): T = throw sys.error("error") def errorSource[T]: Source[T, NotUsed] = - Source.fromPublisher( - (s: Subscriber[_ >: T]) => - s.onSubscribe(new Subscription { - def cancel(): Unit = s.onComplete() - def request(n: Long): Unit = s.onError(new RuntimeException("error")) - }) + Source.fromPublisher((s: Subscriber[_ >: T]) => + s.onSubscribe(new Subscription { + def cancel(): Unit = s.onComplete() + def request(n: Long): Unit = s.onError(new RuntimeException("error")) + }) ) "a sink accumulator" should { diff --git a/core/play/src/main/scala/play/api/Application.scala b/core/play/src/main/scala/play/api/Application.scala index 8881b3b3529..d2377fd46d7 100644 --- a/core/play/src/main/scala/play/api/Application.scala +++ b/core/play/src/main/scala/play/api/Application.scala @@ -55,6 +55,7 @@ import scala.reflect.ClassTag msg = "You do not have an implicit Application in scope. If you want to bring the current running Application into context, please use dependency injection." ) trait Application { + /** * The absolute path hosting this application, mainly used by the `getFile(path)` helper method */ @@ -145,6 +146,7 @@ trait Application { } object Application { + /** * Creates a function that caches results of calls to * `app.injector.instanceOf[T]`. The cache speeds up calls @@ -221,6 +223,7 @@ private[play] final case object ApplicationStoppedReason extends CoordinatedShut * Helper to provide the Play built in components. */ trait BuiltInComponents extends I18nComponents with AkkaComponents with AkkaTypedComponents { + /** The application's environment, e.g. it's [[ClassLoader]] and root path. */ def environment: Environment diff --git a/core/play/src/main/scala/play/api/ApplicationLoader.scala b/core/play/src/main/scala/play/api/ApplicationLoader.scala index 70e6dad7c7f..4c200d42764 100644 --- a/core/play/src/main/scala/play/api/ApplicationLoader.scala +++ b/core/play/src/main/scala/play/api/ApplicationLoader.scala @@ -35,6 +35,7 @@ import play.utils.Reflect * Implementations must define a no-arg constructor. */ trait ApplicationLoader { + /** * Load an application given the context. */ @@ -98,6 +99,7 @@ object ApplicationLoader { ) object Context { + /** * Create an application loading context. * diff --git a/core/play/src/main/scala/play/api/Environment.scala b/core/play/src/main/scala/play/api/Environment.scala index 706b6d26637..4fa06f92369 100644 --- a/core/play/src/main/scala/play/api/Environment.scala +++ b/core/play/src/main/scala/play/api/Environment.scala @@ -17,6 +17,7 @@ import java.io.File * @param mode The mode of the application. */ case class Environment(rootPath: File, classLoader: ClassLoader, mode: Mode) { + /** * Retrieves a file relative to the application root path. * @@ -95,6 +96,7 @@ case class Environment(rootPath: File, classLoader: ClassLoader, mode: Mode) { } object Environment { + /** * A simple environment. * diff --git a/core/play/src/main/scala/play/api/Logger.scala b/core/play/src/main/scala/play/api/Logger.scala index e3ff424f694..952cae7ff86 100644 --- a/core/play/src/main/scala/play/api/Logger.scala +++ b/core/play/src/main/scala/play/api/Logger.scala @@ -19,6 +19,7 @@ import scala.collection.JavaConverters._ * Typical logger interface. */ trait LoggerLike { + /** * The underlying SLF4J Logger. */ @@ -329,6 +330,7 @@ object Logger { * */ trait MarkerContext { + /** * @return an SLF4J marker, if one has been defined. */ @@ -336,6 +338,7 @@ trait MarkerContext { } object MarkerContext extends LowPriorityMarkerContextImplicits { + /** * Provides an instance of a MarkerContext from a Marker. The explicit form is useful when * you want to explicitly tag a log message with a particular Marker and you already have a @@ -358,6 +361,7 @@ object MarkerContext extends LowPriorityMarkerContextImplicits { } trait LowPriorityMarkerContextImplicits { + /** * A MarkerContext that returns None. This is used as the "default" marker context if * no implicit MarkerContext is found in local scope (meaning there is nothing defined diff --git a/core/play/src/main/scala/play/api/LoggerConfigurator.scala b/core/play/src/main/scala/play/api/LoggerConfigurator.scala index 556c91f1eff..6f9045a02ca 100644 --- a/core/play/src/main/scala/play/api/LoggerConfigurator.scala +++ b/core/play/src/main/scala/play/api/LoggerConfigurator.scala @@ -14,6 +14,7 @@ import org.slf4j.ILoggerFactory * Runs through underlying logger configuration. */ trait LoggerConfigurator { + /** * Initialize the Logger when there's no application ClassLoader available. */ diff --git a/core/play/src/main/scala/play/api/data/Form.scala b/core/play/src/main/scala/play/api/data/Form.scala index 8d38a05ebf4..66fb6bff745 100644 --- a/core/play/src/main/scala/play/api/data/Form.scala +++ b/core/play/src/main/scala/play/api/data/Form.scala @@ -39,6 +39,7 @@ import play.api.templates.PlayMagic.translate * @param value a concrete value of type `T` if the form submission was successful */ case class Form[T](mapping: Mapping[T], data: Map[String, String], errors: Seq[FormError], value: Option[T]) { + /** * Constraints associated with this form, indexed by field name. */ @@ -299,6 +300,7 @@ case class Field( errors: Seq[FormError], value: Option[String] ) { + /** * The field ID - the same as the field name but with '.' replaced by '_'. */ @@ -340,6 +342,7 @@ case class Field( * Provides a set of operations for creating `Form` values. */ object Form { + /** * Creates a new form from a mapping. * @@ -590,6 +593,7 @@ case class WrappedMapping[A, B]( f2: B => A, additionalConstraints: Seq[Constraint[B]] = Nil ) extends Mapping[B] { + /** * The field key. */ @@ -671,6 +675,7 @@ case class WrappedMapping[A, B]( * Provides a set of operations related to `RepeatedMapping` values. */ object RepeatedMapping { + /** * Computes the available indexes for the given key in this set of data. */ @@ -690,6 +695,7 @@ case class RepeatedMapping[T]( key: String = "", constraints: Seq[Constraint[List[T]]] = Nil ) extends Mapping[List[T]] { + /** * The Format expected for this field, if it exists. */ @@ -861,6 +867,7 @@ case class OptionalMapping[T](wrapped: Mapping[T], constraints: Seq[Constraint[O case class FieldMapping[T](key: String = "", constraints: Seq[Constraint[T]] = Nil)( implicit val binder: Formatter[T] ) extends Mapping[T] { + /** * The Format expected for this field, if it exists. */ @@ -942,6 +949,7 @@ case class FieldMapping[T](key: String = "", constraints: Seq[Constraint[T]] = N * Common helper methods for all object mappings - mappings including several fields. */ trait ObjectMapping { + /** * Merges the result of two bindings. * diff --git a/core/play/src/main/scala/play/api/data/Forms.scala b/core/play/src/main/scala/play/api/data/Forms.scala index f78158e7fa2..20ce5a87407 100644 --- a/core/play/src/main/scala/play/api/data/Forms.scala +++ b/core/play/src/main/scala/play/api/data/Forms.scala @@ -25,6 +25,7 @@ import play.api.data.validation._ * */ object Forms { + /** * Creates a Mapping of type `T`. * diff --git a/core/play/src/main/scala/play/api/data/format/Format.scala b/core/play/src/main/scala/play/api/data/format/Format.scala index b1f9161a5ad..44a08942f82 100644 --- a/core/play/src/main/scala/play/api/data/format/Format.scala +++ b/core/play/src/main/scala/play/api/data/format/Format.scala @@ -20,6 +20,7 @@ import annotation.implicitNotFound msg = "Cannot find Formatter type class for ${T}. Perhaps you will need to import play.api.data.format.Formats._ " ) trait Formatter[T] { + /** * The expected format of `Any`. */ @@ -46,6 +47,7 @@ trait Formatter[T] { /** This object defines several default formatters. */ object Formats { + /** * Formatter for ignored values. * diff --git a/core/play/src/main/scala/play/api/data/validation/Validation.scala b/core/play/src/main/scala/play/api/data/validation/Validation.scala index a0701408399..8ddba381759 100644 --- a/core/play/src/main/scala/play/api/data/validation/Validation.scala +++ b/core/play/src/main/scala/play/api/data/validation/Validation.scala @@ -15,6 +15,7 @@ import play.api.libs.json.JsonValidationError * @param f the validation function */ case class Constraint[-T](name: Option[String], args: Seq[Any])(f: (T => ValidationResult)) { + /** * Run the constraint validation. * @@ -36,6 +37,7 @@ case class Constraint[-T](name: Option[String], args: Seq[Any])(f: (T => Validat * }}} */ object Constraint { + /** * Creates a new anonymous constraint from a validation function. * @@ -215,6 +217,7 @@ case object Valid extends ValidationResult * @param errors the resulting errors */ case class Invalid(errors: Seq[ValidationError]) extends ValidationResult { + /** * Combines these validation errors with another validation failure. * @@ -228,6 +231,7 @@ case class Invalid(errors: Seq[ValidationError]) extends ValidationResult { * This object provides helper methods to construct `Invalid` values. */ object Invalid { + /** * Creates an `Invalid` value with a single error. * @@ -277,6 +281,7 @@ case class ValidationError(messages: Seq[String], args: Any*) { } object ValidationError { + /** * Conversion from a JsonValidationError to a Play ValidationError. */ diff --git a/core/play/src/main/scala/play/api/http/AcceptEncoding.scala b/core/play/src/main/scala/play/api/http/AcceptEncoding.scala index 18e0cdc4e16..1b491b60270 100644 --- a/core/play/src/main/scala/play/api/http/AcceptEncoding.scala +++ b/core/play/src/main/scala/play/api/http/AcceptEncoding.scala @@ -34,6 +34,7 @@ object ContentEncoding { * name (or *), and an optional q-value. */ case class EncodingPreference(name: String = "*", qValue: Option[BigDecimal] = None) { + /** * `true` if this is a wildcard `*` preference. */ @@ -51,6 +52,7 @@ case class EncodingPreference(name: String = "*", qValue: Option[BigDecimal] = N } object EncodingPreference { + /** * Ordering for encodings, in order of highest priority to lowest priority. */ @@ -77,6 +79,7 @@ object EncodingPreference { * A representation of the Accept-Encoding header */ trait AcceptEncoding { + /** * The list of Accept-Encoding headers in order of appearance */ diff --git a/core/play/src/main/scala/play/api/http/ContentTypeOf.scala b/core/play/src/main/scala/play/api/http/ContentTypeOf.scala index 64563561365..1f73d7a7e98 100644 --- a/core/play/src/main/scala/play/api/http/ContentTypeOf.scala +++ b/core/play/src/main/scala/play/api/http/ContentTypeOf.scala @@ -29,6 +29,7 @@ object ContentTypeOf extends DefaultContentTypeOfs * Contains typeclasses for ContentTypeOf. */ trait DefaultContentTypeOfs { + /** * Default content type for `Html` values (`text/html`). */ diff --git a/core/play/src/main/scala/play/api/http/FileMimeTypes.scala b/core/play/src/main/scala/play/api/http/FileMimeTypes.scala index 7e63bbfc13c..6486e10124a 100644 --- a/core/play/src/main/scala/play/api/http/FileMimeTypes.scala +++ b/core/play/src/main/scala/play/api/http/FileMimeTypes.scala @@ -51,6 +51,7 @@ import scala.annotation.implicitNotFound "You do not have an implicit FileMimeTypes in scope. If you want to bring a FileMimeTypes into context, please use dependency injection." ) trait FileMimeTypes { + /** * Retrieves the usual MIME type for a given file name * @@ -75,6 +76,7 @@ class DefaultFileMimeTypesProvider @Inject() (fileMimeTypesConfiguration: FileMi * Default implementation of FileMimeTypes. */ class DefaultFileMimeTypes @Inject() (config: FileMimeTypesConfiguration) extends FileMimeTypes { + /** * Retrieves the usual MIME type for a given file name * diff --git a/core/play/src/main/scala/play/api/http/HttpEntity.scala b/core/play/src/main/scala/play/api/http/HttpEntity.scala index 693b9791bf1..1efcc6bc9ae 100644 --- a/core/play/src/main/scala/play/api/http/HttpEntity.scala +++ b/core/play/src/main/scala/play/api/http/HttpEntity.scala @@ -19,6 +19,7 @@ import scala.concurrent.Future * HTTP entities come in three flavors, [[HttpEntity.Strict]], [[HttpEntity.Streamed]] and [[HttpEntity.Chunked]]. */ sealed trait HttpEntity { + /** * The content type of the entity, if known. */ @@ -60,6 +61,7 @@ sealed trait HttpEntity { } object HttpEntity { + /** * No entity. */ @@ -132,6 +134,7 @@ object HttpEntity { sealed trait HttpChunk {} object HttpChunk { + /** * A chunk. * diff --git a/core/play/src/main/scala/play/api/http/HttpErrorHandler.scala b/core/play/src/main/scala/play/api/http/HttpErrorHandler.scala index a42d15f8c2f..d5093a679bd 100644 --- a/core/play/src/main/scala/play/api/http/HttpErrorHandler.scala +++ b/core/play/src/main/scala/play/api/http/HttpErrorHandler.scala @@ -32,6 +32,7 @@ import scala.util.control.NonFatal * @since 2.4.0 */ trait HttpErrorHandler { + /** * Invoked when a client error occurs, that is, an error in the 4xx series. * @@ -95,6 +96,7 @@ object PreferredMediaTypeHttpErrorHandler { } object HttpErrorHandler { + /** * Get the bindings for the error handler from the configuration */ @@ -312,6 +314,7 @@ class DefaultHttpErrorHandler( * Extracted so the Java default error handler can reuse this functionality */ object HttpErrorHandlerExceptions { + /** * Convert the given exception to an exception that Play can report more information about. * diff --git a/core/play/src/main/scala/play/api/http/HttpFilters.scala b/core/play/src/main/scala/play/api/http/HttpFilters.scala index fa6bd6a8c7d..6f4240405ef 100644 --- a/core/play/src/main/scala/play/api/http/HttpFilters.scala +++ b/core/play/src/main/scala/play/api/http/HttpFilters.scala @@ -23,6 +23,7 @@ import scala.collection.JavaConverters._ * Provides filters to the [[play.api.http.HttpRequestHandler]]. */ trait HttpFilters { + /** * Return the filters that should filter every request */ diff --git a/core/play/src/main/scala/play/api/http/HttpRequestHandler.scala b/core/play/src/main/scala/play/api/http/HttpRequestHandler.scala index 66cdc26aa38..ee86ed8bd8b 100644 --- a/core/play/src/main/scala/play/api/http/HttpRequestHandler.scala +++ b/core/play/src/main/scala/play/api/http/HttpRequestHandler.scala @@ -27,6 +27,7 @@ import play.utils.Reflect * Primary entry point for all HTTP requests on Play applications. */ trait HttpRequestHandler { + /** * Get a handler for the given request. * diff --git a/core/play/src/main/scala/play/api/http/MediaRange.scala b/core/play/src/main/scala/play/api/http/MediaRange.scala index 56ffd173edf..c52f1b6f2e5 100644 --- a/core/play/src/main/scala/play/api/http/MediaRange.scala +++ b/core/play/src/main/scala/play/api/http/MediaRange.scala @@ -51,6 +51,7 @@ class MediaRange( val qValue: Option[BigDecimal], val acceptExtensions: Seq[(String, Option[String])] ) extends MediaType(mediaType, mediaSubType, parameters) { + /** * @return true if `mimeType` matches this media type, otherwise false */ diff --git a/core/play/src/main/scala/play/api/http/StandardValues.scala b/core/play/src/main/scala/play/api/http/StandardValues.scala index c1586978edd..88d35e74ba3 100644 --- a/core/play/src/main/scala/play/api/http/StandardValues.scala +++ b/core/play/src/main/scala/play/api/http/StandardValues.scala @@ -97,6 +97,7 @@ object MimeTypes extends MimeTypes /** Common HTTP MIME types */ trait MimeTypes { + /** * Content-Type of text. */ diff --git a/core/play/src/main/scala/play/api/http/Writeable.scala b/core/play/src/main/scala/play/api/http/Writeable.scala index 33affe9bc22..b0763e2ec71 100644 --- a/core/play/src/main/scala/play/api/http/Writeable.scala +++ b/core/play/src/main/scala/play/api/http/Writeable.scala @@ -44,6 +44,7 @@ object Writeable extends DefaultWriteables { * Default Writeable with lower priority. */ trait LowPriorityWriteables { + /** * `Writeable` for `play.twirl.api.Content` values. */ @@ -59,6 +60,7 @@ trait LowPriorityWriteables { * Default Writeable. */ trait DefaultWriteables extends LowPriorityWriteables { + /** * `Writeable` for `play.twirl.api.Xml` values. Trims surrounding whitespace. */ @@ -88,15 +90,14 @@ trait DefaultWriteables extends LowPriorityWriteables { */ implicit def writeableOf_urlEncodedForm(implicit codec: Codec): Writeable[Map[String, Seq[String]]] = { import java.net.URLEncoder - Writeable( - formData => - codec.encode( - formData - .flatMap({ item => - item._2.map(c => URLEncoder.encode(item._1, "UTF-8") + "=" + URLEncoder.encode(c, "UTF-8")) - }) - .mkString("&") - ) + Writeable(formData => + codec.encode( + formData + .flatMap({ item => + item._2.map(c => URLEncoder.encode(item._1, "UTF-8") + "=" + URLEncoder.encode(c, "UTF-8")) + }) + .mkString("&") + ) ) } diff --git a/core/play/src/main/scala/play/api/http/package.scala b/core/play/src/main/scala/play/api/http/package.scala index adcc00e1537..0fbb74e9ed2 100644 --- a/core/play/src/main/scala/play/api/http/package.scala +++ b/core/play/src/main/scala/play/api/http/package.scala @@ -17,6 +17,7 @@ import java.time.ZoneId * }}} */ package object http { + /** HTTP date formatter, compliant to RFC 1123 */ val dateFormat = DateTimeFormatter .ofPattern("EEE, dd MMM yyyy HH:mm:ss 'GMT'") diff --git a/core/play/src/main/scala/play/api/i18n/I18nSupport.scala b/core/play/src/main/scala/play/api/i18n/I18nSupport.scala index d80b440f1dd..76854102c01 100644 --- a/core/play/src/main/scala/play/api/i18n/I18nSupport.scala +++ b/core/play/src/main/scala/play/api/i18n/I18nSupport.scala @@ -46,10 +46,12 @@ object I18nSupport extends I18NSupportLowPriorityImplicits * Implicit conversions for using i18n with requests and results. */ trait I18NSupportLowPriorityImplicits { + /** * Adds convenient methods to handle the messages. */ implicit class RequestWithMessagesApi(request: RequestHeader) { + /** * Adds a `messages` method that can be used on a request, * returning the Messages object in the preferred language @@ -85,6 +87,7 @@ trait I18NSupportLowPriorityImplicits { * Adds convenient methods to handle the client-side language */ implicit class ResultWithMessagesApi(result: Result) { + /** * Sets the user's language permanently for future requests by storing it in a cookie. * diff --git a/core/play/src/main/scala/play/api/i18n/Langs.scala b/core/play/src/main/scala/play/api/i18n/Langs.scala index fcae32afb0a..0c2a9117336 100644 --- a/core/play/src/main/scala/play/api/i18n/Langs.scala +++ b/core/play/src/main/scala/play/api/i18n/Langs.scala @@ -20,6 +20,7 @@ import scala.collection.JavaConverters._ * A Lang supported by the application. */ case class Lang(locale: Locale) { + /** * Convert to a Java Locale value. */ @@ -136,6 +137,7 @@ object Lang { * Manages languages in Play */ trait Langs { + /** * The available languages. * diff --git a/core/play/src/main/scala/play/api/i18n/Messages.scala b/core/play/src/main/scala/play/api/i18n/Messages.scala index 6c5da184889..b2d254ea167 100644 --- a/core/play/src/main/scala/play/api/i18n/Messages.scala +++ b/core/play/src/main/scala/play/api/i18n/Messages.scala @@ -35,6 +35,7 @@ import scala.util.parsing.input._ * }}} */ object Messages extends MessagesImplicits { + /** * Request Attributes for the MessagesApi * Currently all Attributes are only available inside the [[MessagesApi]] methods. @@ -97,6 +98,7 @@ object Messages extends MessagesImplicits { * A source for messages */ trait MessageSource { + /** * Read the message source as a String */ @@ -182,6 +184,7 @@ object Messages extends MessagesImplicits { * @param messagesApi The messages API */ case class MessagesImpl(lang: Lang, messagesApi: MessagesApi) extends Messages { + /** * Translates a message. * @@ -249,6 +252,7 @@ case class MessagesImpl(lang: Lang, messagesApi: MessagesApi) extends Messages { "An implicit Messages instance was not found. Please see https://www.playframework.com/documentation/latest/ScalaI18N" ) trait Messages extends MessagesProvider { + /** * Every Messages is also a MessagesProvider. * @@ -330,6 +334,7 @@ trait MessagesImplicits { * The internationalisation API. */ trait MessagesApi { + /** * Get all the defined messages */ @@ -504,10 +509,9 @@ class DefaultMessagesApi @Inject() ( message <- messages.get(key) } yield message) } - pattern.map( - p => - new MessageFormat(p, lang.toLocale) - .format(args.map(_.asInstanceOf[Object]).toArray) + pattern.map(p => + new MessageFormat(p, lang.toLocale) + .format(args.map(_.asInstanceOf[Object]).toArray) ) } diff --git a/core/play/src/main/scala/play/api/inject/ApplicationLifecycle.scala b/core/play/src/main/scala/play/api/inject/ApplicationLifecycle.scala index 8432196aa00..cad7a57aa2c 100644 --- a/core/play/src/main/scala/play/api/inject/ApplicationLifecycle.scala +++ b/core/play/src/main/scala/play/api/inject/ApplicationLifecycle.scala @@ -58,6 +58,7 @@ import scala.util.Try * }}} */ trait ApplicationLifecycle { + /** * Add a stop hook to be called when the application stops. * diff --git a/core/play/src/main/scala/play/api/inject/Binding.scala b/core/play/src/main/scala/play/api/inject/Binding.scala index fed9784af1c..a00c1737320 100644 --- a/core/play/src/main/scala/play/api/inject/Binding.scala +++ b/core/play/src/main/scala/play/api/inject/Binding.scala @@ -40,6 +40,7 @@ final case class Binding[T]( eager: Boolean, source: Object ) { + /** * Configure the scope for this binding. */ diff --git a/core/play/src/main/scala/play/api/inject/Injector.scala b/core/play/src/main/scala/play/api/inject/Injector.scala index a2c52df9856..c928622e378 100644 --- a/core/play/src/main/scala/play/api/inject/Injector.scala +++ b/core/play/src/main/scala/play/api/inject/Injector.scala @@ -20,6 +20,7 @@ import scala.reflect.ClassTag * */ trait Injector { + /** * Get an instance of the given class from the injector. */ @@ -45,6 +46,7 @@ trait Injector { * An injector that simply creates a new instance of the passed in classes using the classes no-arg constructor. */ object NewInstanceInjector extends Injector { + /** * Get an instance of the given class from the injector. */ @@ -81,6 +83,7 @@ object NewInstanceInjector extends Injector { * @param components The components that this injector provides. */ class SimpleInjector(fallback: Injector, components: Map[Class[_], Any] = Map.empty) extends Injector { + /** * Get an instance of the given class from the injector. */ diff --git a/core/play/src/main/scala/play/api/inject/Module.scala b/core/play/src/main/scala/play/api/inject/Module.scala index 15d3663c071..680bda0041c 100644 --- a/core/play/src/main/scala/play/api/inject/Module.scala +++ b/core/play/src/main/scala/play/api/inject/Module.scala @@ -43,6 +43,7 @@ import scala.reflect.ClassTag * }}} */ abstract class Module { + /** * Get the bindings provided by this module. * @@ -149,13 +150,14 @@ object Modules { val moduleClass = loadModuleClass() def tryConstruct(args: AnyRef*): Option[T] = { - val constructor: Option[Constructor[T]] = try { - val argTypes = args.map(_.getClass) - Option(ConstructorUtils.getMatchingAccessibleConstructor(moduleClass, argTypes: _*)) - } catch { - case _: NoSuchMethodException => None - case _: SecurityException => None - } + val constructor: Option[Constructor[T]] = + try { + val argTypes = args.map(_.getClass) + Option(ConstructorUtils.getMatchingAccessibleConstructor(moduleClass, argTypes: _*)) + } catch { + case _: NoSuchMethodException => None + case _: SecurityException => None + } constructor.map(_.newInstance(args: _*)) } diff --git a/core/play/src/main/scala/play/api/inject/package.scala b/core/play/src/main/scala/play/api/inject/package.scala index ec610f16af4..50f9d0a28c6 100644 --- a/core/play/src/main/scala/play/api/inject/package.scala +++ b/core/play/src/main/scala/play/api/inject/package.scala @@ -29,6 +29,7 @@ import scala.reflect.ClassTag * @see The [[play.api.inject.Module Module]] class for information on how to provide bindings. */ package object inject { + /** * Create a binding key for the given class. * diff --git a/core/play/src/main/scala/play/api/internal/libs/concurrent/CoordinatedShutdownSupport.scala b/core/play/src/main/scala/play/api/internal/libs/concurrent/CoordinatedShutdownSupport.scala index 6e5998b21f7..4616c125cb5 100644 --- a/core/play/src/main/scala/play/api/internal/libs/concurrent/CoordinatedShutdownSupport.scala +++ b/core/play/src/main/scala/play/api/internal/libs/concurrent/CoordinatedShutdownSupport.scala @@ -25,6 +25,7 @@ import scala.concurrent.TimeoutException // This is public so that it can be used in Lagom without any hacks or copy-and-paste. @InternalApi object CoordinatedShutdownSupport { + /** * Shuts down the provided `ActorSystem` asynchronously, starting from the configured phase. * diff --git a/core/play/src/main/scala/play/api/libs/Collections.scala b/core/play/src/main/scala/play/api/libs/Collections.scala index 996ed93cc68..6d6e15e762f 100644 --- a/core/play/src/main/scala/play/api/libs/Collections.scala +++ b/core/play/src/main/scala/play/api/libs/Collections.scala @@ -8,6 +8,7 @@ package play.api.libs * Utilities functions for Collections */ object Collections { + /** * Produces a Seq from a seed and a function. * diff --git a/core/play/src/main/scala/play/api/libs/EventSource.scala b/core/play/src/main/scala/play/api/libs/EventSource.scala index af4b169c5bd..f022a43ce11 100644 --- a/core/play/src/main/scala/play/api/libs/EventSource.scala +++ b/core/play/src/main/scala/play/api/libs/EventSource.scala @@ -41,6 +41,7 @@ import play.api.libs.json.JsValue * }}} */ object EventSource { + /** * Makes a `Flow[E, Event, _]`, given an input source. * @@ -63,6 +64,7 @@ object EventSource { * An event encoded with the SSE protocol.. */ case class Event(data: String, id: Option[String], name: Option[String]) { + /** * This event, formatted according to the EventSource protocol. */ @@ -79,6 +81,7 @@ object EventSource { } object Event { + /** * Creates an event from a single input, using implicit extractors to provide raw values. * diff --git a/core/play/src/main/scala/play/api/libs/Files.scala b/core/play/src/main/scala/play/api/libs/Files.scala index ee96c2aba51..e4bfbd0a073 100644 --- a/core/play/src/main/scala/play/api/libs/Files.scala +++ b/core/play/src/main/scala/play/api/libs/Files.scala @@ -44,6 +44,7 @@ object Files { * try to clean up any leaked files, e.g. when the Application or JVM stops. */ trait TemporaryFileCreator { + /** * Creates a temporary file. * @@ -100,12 +101,13 @@ object Files { * @param replace if it should replace an existing file. */ def copyTo(to: Path, replace: Boolean): Path = { - val destination = try if (replace) JFiles.copy(path, to, StandardCopyOption.REPLACE_EXISTING) - else if (!to.toFile.exists()) JFiles.copy(path, to) - else to - catch { - case _: FileAlreadyExistsException => to - } + val destination = + try if (replace) JFiles.copy(path, to, StandardCopyOption.REPLACE_EXISTING) + else if (!to.toFile.exists()) JFiles.copy(path, to) + else to + catch { + case _: FileAlreadyExistsException => to + } destination } @@ -151,15 +153,16 @@ object Files { * @param replace true if an existing file should be replaced, false otherwise. */ def moveTo(to: Path, replace: Boolean): Path = { - val destination = try { - if (replace) - JFiles.move(path, to, StandardCopyOption.REPLACE_EXISTING) - else if (!to.toFile.exists()) - JFiles.move(path, to) - else to - } catch { - case ex: FileAlreadyExistsException => to - } + val destination = + try { + if (replace) + JFiles.move(path, to, StandardCopyOption.REPLACE_EXISTING) + else if (!to.toFile.exists()) + JFiles.move(path, to) + else to + } catch { + case ex: FileAlreadyExistsException => to + } destination } @@ -209,22 +212,23 @@ object Files { */ // see https://github.com/apache/kafka/blob/d345d53/clients/src/main/java/org/apache/kafka/common/utils/Utils.java#L608-L626 def atomicMoveWithFallback(to: Path): Path = { - val destination = try { - JFiles.move(path, to, StandardCopyOption.ATOMIC_MOVE) - } catch { - case outer: IOException => - try { - val p = JFiles.move(path, to, StandardCopyOption.REPLACE_EXISTING) - logger.debug( - s"Non-atomic move of $path to $to succeeded after atomic move failed due to ${outer.getMessage}" - ) - p - } catch { - case inner: IOException => - inner.addSuppressed(outer) - throw inner - } - } + val destination = + try { + JFiles.move(path, to, StandardCopyOption.ATOMIC_MOVE) + } catch { + case outer: IOException => + try { + val p = JFiles.move(path, to, StandardCopyOption.REPLACE_EXISTING) + logger.debug( + s"Non-atomic move of $path to $to succeeded after atomic move failed due to ${outer.getMessage}" + ) + p + } catch { + case inner: IOException => + inner.addSuppressed(outer) + throw inner + } + } destination } @@ -502,6 +506,7 @@ object Files { * Utilities to manage temporary files. */ object TemporaryFile { + /** * Implicitly converts a [[TemporaryFile]] to a plain old [[java.io.File]]. */ diff --git a/core/play/src/main/scala/play/api/libs/concurrent/Akka.scala b/core/play/src/main/scala/play/api/libs/concurrent/Akka.scala index 2742958cca0..f60d68bc2e6 100644 --- a/core/play/src/main/scala/play/api/libs/concurrent/Akka.scala +++ b/core/play/src/main/scala/play/api/libs/concurrent/Akka.scala @@ -34,6 +34,7 @@ import scala.util.Try * Helper to access the application defined Akka Actor system. */ object Akka { + /** * Create a provider for an actor implemented by the given class, with the given name. * @@ -237,6 +238,7 @@ object ActorSystemProvider { * Support for creating injected child actors. */ trait InjectedActorSupport { + /** * Create an injected child actor. * diff --git a/core/play/src/main/scala/play/api/libs/concurrent/Futures.scala b/core/play/src/main/scala/play/api/libs/concurrent/Futures.scala index 29a3554e6c6..a6db935d900 100644 --- a/core/play/src/main/scala/play/api/libs/concurrent/Futures.scala +++ b/core/play/src/main/scala/play/api/libs/concurrent/Futures.scala @@ -51,6 +51,7 @@ import scala.language.implicitConversions * @see [[http://docs.scala-lang.org/overviews/core/futures.html Futures and Promises]] */ trait Futures { + /** * Creates a future which will resolve to a timeout exception if the * given Future has not successfully completed within timeoutDuration. @@ -140,6 +141,7 @@ class DefaultFutures @Inject() (actorSystem: ActorSystem) extends Futures { */ trait LowPriorityFuturesImplicits { implicit class FutureOps[T](future: Future[T]) { + /** * Creates a future which will resolve to a timeout exception if the * given [[scala.concurrent.Future]] has not successfully completed within timeoutDuration. diff --git a/core/play/src/main/scala/play/api/libs/crypto/CSRFTokenSigner.scala b/core/play/src/main/scala/play/api/libs/crypto/CSRFTokenSigner.scala index 10c413db4aa..ebdb56e417d 100644 --- a/core/play/src/main/scala/play/api/libs/crypto/CSRFTokenSigner.scala +++ b/core/play/src/main/scala/play/api/libs/crypto/CSRFTokenSigner.scala @@ -21,6 +21,7 @@ import play.api.libs.Codecs * This trait should not be used as a general purpose encryption utility. */ trait CSRFTokenSigner { + /** * Sign a token. This produces a new token, that has this token signed with a nonce. * @@ -142,6 +143,7 @@ class DefaultCSRFTokenSigner @Inject() (signer: CookieSigner, clock: Clock) exte @deprecated("CSRFTokenSigner's singleton object can be replaced by MessageDigest.isEqual", "2.6.0") object CSRFTokenSigner { + /** * @deprecated Please use [[java.security.MessageDigest.isEqual]] over this method. */ diff --git a/core/play/src/main/scala/play/api/libs/crypto/CookieSigner.scala b/core/play/src/main/scala/play/api/libs/crypto/CookieSigner.scala index 786220d09f2..54dba8fd4b1 100644 --- a/core/play/src/main/scala/play/api/libs/crypto/CookieSigner.scala +++ b/core/play/src/main/scala/play/api/libs/crypto/CookieSigner.scala @@ -21,6 +21,7 @@ import play.libs.crypto * This trait should not be used as a general purpose MAC utility. */ trait CookieSigner { + /** * Signs (MAC) the given String using the given secret key. * diff --git a/core/play/src/main/scala/play/api/libs/typedmap/TypedEntry.scala b/core/play/src/main/scala/play/api/libs/typedmap/TypedEntry.scala index 4b90d4bb689..cf6d4b8fce1 100644 --- a/core/play/src/main/scala/play/api/libs/typedmap/TypedEntry.scala +++ b/core/play/src/main/scala/play/api/libs/typedmap/TypedEntry.scala @@ -14,6 +14,7 @@ package play.api.libs.typedmap * @tparam A The type of the value. */ final case class TypedEntry[A](key: TypedKey[A], value: A) { + /** * Convert the entry into a standard pair. */ diff --git a/core/play/src/main/scala/play/api/libs/typedmap/TypedKey.scala b/core/play/src/main/scala/play/api/libs/typedmap/TypedKey.scala index b75ad83ea62..675aabea52d 100644 --- a/core/play/src/main/scala/play/api/libs/typedmap/TypedKey.scala +++ b/core/play/src/main/scala/play/api/libs/typedmap/TypedKey.scala @@ -15,6 +15,7 @@ package play.api.libs.typedmap * @tparam A The type of values associated with this key. */ final class TypedKey[A] private (val displayName: Option[String]) { + /** * Bind this key to a value. This is equivalent to the `->` operator. * @@ -43,6 +44,7 @@ final class TypedKey[A] private (val displayName: Option[String]) { * Helper for working with `TypedKey`s. */ object TypedKey { + /** * Creates a [[TypedKey]] without a name. * diff --git a/core/play/src/main/scala/play/api/libs/typedmap/TypedMap.scala b/core/play/src/main/scala/play/api/libs/typedmap/TypedMap.scala index a90fd38e8c0..e51ccbaa93a 100644 --- a/core/play/src/main/scala/play/api/libs/typedmap/TypedMap.scala +++ b/core/play/src/main/scala/play/api/libs/typedmap/TypedMap.scala @@ -21,6 +21,7 @@ import scala.collection.immutable * corresponding [[TypedKey]]. */ trait TypedMap { + /** * Get a value from the map, throwing an exception if it is not present. * @@ -81,6 +82,7 @@ trait TypedMap { } object TypedMap { + /** * The empty [[TypedMap]] instance. */ diff --git a/core/play/src/main/scala/play/api/mvc/Action.scala b/core/play/src/main/scala/play/api/mvc/Action.scala index 42a3340a383..5028063e0e1 100644 --- a/core/play/src/main/scala/play/api/mvc/Action.scala +++ b/core/play/src/main/scala/play/api/mvc/Action.scala @@ -458,6 +458,7 @@ class DefaultActionBuilderImpl(parser: BodyParser[AnyContent])(implicit ec: Exec * The critical (abstract) function is refine. */ trait ActionRefiner[-R[_], +P[_]] extends ActionFunction[R, P] { + /** * Determine how to process a request. This is the main method than an ActionRefiner has to implement. * It can decide to immediately intercept the request and return a Result (Left), or continue processing with a new parameter of type P (Right). @@ -477,6 +478,7 @@ trait ActionRefiner[-R[_], +P[_]] extends ActionFunction[R, P] { * its Action block. The critical (abstract) function is transform. */ trait ActionTransformer[-R[_], +P[_]] extends ActionRefiner[R, P] { + /** * Augment or transform an existing request. This is the main method that an ActionTransformer has to implement. * @@ -495,6 +497,7 @@ trait ActionTransformer[-R[_], +P[_]] extends ActionRefiner[R, P] { * The critical (abstract) function is filter. */ trait ActionFilter[R[_]] extends ActionRefiner[R, R] { + /** * Determine whether to process a request. This is the main method that an ActionFilter has to implement. * It can decide to immediately intercept the request and return a Result (Some), or continue processing (None). diff --git a/core/play/src/main/scala/play/api/mvc/Binders.scala b/core/play/src/main/scala/play/api/mvc/Binders.scala index 362222a5857..6a5f7e344cb 100644 --- a/core/play/src/main/scala/play/api/mvc/Binders.scala +++ b/core/play/src/main/scala/play/api/mvc/Binders.scala @@ -192,6 +192,7 @@ trait PathBindable[A] { "No JavaScript literal binder found for type ${A}. Try to implement an implicit JavascriptLiteral for this type." ) trait JavascriptLiteral[A] { + /** * Convert a value of A to a JavaScript literal. */ @@ -202,6 +203,7 @@ trait JavascriptLiteral[A] { * Default JavaScript literals converters. */ object JavascriptLiteral { + /** * Convert a (primitive) value to it's Javascript equivalent */ diff --git a/core/play/src/main/scala/play/api/mvc/BodyParsers.scala b/core/play/src/main/scala/play/api/mvc/BodyParsers.scala index 605fd71b57a..83f38a91bef 100644 --- a/core/play/src/main/scala/play/api/mvc/BodyParsers.scala +++ b/core/play/src/main/scala/play/api/mvc/BodyParsers.scala @@ -46,6 +46,7 @@ import scala.xml._ * A request body that adapts automatically according the request Content-Type. */ sealed trait AnyContent { + /** * application/x-www-form-urlencoded */ @@ -147,6 +148,7 @@ case class AnyContentAsMultipartFormData(mfd: MultipartFormData[TemporaryFile]) * Multipart form data body. */ case class MultipartFormData[A](dataParts: Map[String, Seq[String]], files: Seq[FilePart[A]], badParts: Seq[BadPart]) { + /** * Extract the data parts as Form url encoded. */ @@ -162,6 +164,7 @@ case class MultipartFormData[A](dataParts: Map[String, Seq[String]], files: Seq[ * Defines parts handled by Multipart form data. */ object MultipartFormData { + /** * A part. * @@ -294,6 +297,7 @@ case class RawBuffer( * A set of reusable body parsers and utilities that do not require configuration. */ trait BodyParserUtils { + /** * Don't parse the body content. */ @@ -371,6 +375,7 @@ trait BodyParserUtils { } object BodyParserUtils { + /** * @param request The request whose Content-Length header will be checked (if it exists). * @param maxLength Maximum allowed bytes. @@ -392,6 +397,7 @@ class DefaultPlayBodyParsers @Inject() ( ) extends PlayBodyParsers object PlayBodyParsers { + /** * A helper method for creating PlayBodyParsers. The default values are mainly useful in testing, and default the * TemporaryFileCreator and HttpErrorHandler to singleton versions. @@ -1038,10 +1044,12 @@ trait PlayBodyParsers extends BodyParserUtils { * Default BodyParsers. */ object BodyParsers { + /** * The default body parser provided by Play */ class Default @Inject() (parse: PlayBodyParsers) extends BodyParser[AnyContent] { + /** * An alternate constructor primarily designed for unit testing. Default values are set to empty or singleton * implementations where appropriate. diff --git a/core/play/src/main/scala/play/api/mvc/Controller.scala b/core/play/src/main/scala/play/api/mvc/Controller.scala index 114810eaddc..0c86ba2821b 100644 --- a/core/play/src/main/scala/play/api/mvc/Controller.scala +++ b/core/play/src/main/scala/play/api/mvc/Controller.scala @@ -35,6 +35,7 @@ trait ControllerHelpers with RequestExtractors with Rendering with RequestImplicits { + /** * Used to mark an action that is still not implemented, e.g.: * @@ -56,6 +57,7 @@ object ControllerHelpers extends ControllerHelpers * you can mix in this trait. */ trait BaseControllerHelpers extends ControllerHelpers { + /** * The components needed to use the controller methods */ @@ -103,6 +105,7 @@ trait BaseControllerHelpers extends ControllerHelpers { * Useful mixin for methods that do implicit transformations of a request */ trait RequestImplicits { + /** * Retrieves the session implicitly from the request. * @@ -150,6 +153,7 @@ trait RequestImplicits { * base controller class, or write your own version with similar code. */ trait BaseController extends BaseControllerHelpers { + /** * The default ActionBuilder. Used to construct an action, for example: * diff --git a/core/play/src/main/scala/play/api/mvc/Cookie.scala b/core/play/src/main/scala/play/api/mvc/Cookie.scala index 65178c7bf24..72a85d8fcfd 100644 --- a/core/play/src/main/scala/play/api/mvc/Cookie.scala +++ b/core/play/src/main/scala/play/api/mvc/Cookie.scala @@ -136,6 +136,7 @@ case class DiscardingCookie(name: String, path: String = "/", domain: Option[Str * The HTTP cookies set. */ trait Cookies extends Traversable[Cookie] { + /** * Optionally returns the cookie associated with a key. */ @@ -351,6 +352,7 @@ class DefaultCookieHeaderEncoding @Inject() ( * Utilities for merging individual cookie values in HTTP cookie headers. */ object CookieHeaderMerging { + /** * Merge the elements in a sequence so that there is only one occurrence of * elements when mapped by a discriminator function. @@ -481,6 +483,7 @@ trait CookieBaker[T <: AnyRef] { self: CookieDataCodec => * This trait encodes and decodes data to a string used as cookie value. */ trait CookieDataCodec { + /** * Encodes the data as a `String`. */ @@ -664,6 +667,7 @@ trait JWTCookieDataCodec extends CookieDataCodec { } object JWTCookieDataCodec { + /** * Maps to and from JWT claims. This class is more basic than the JWT * cookie signing, because it exposes all claims, not just the "data" ones. diff --git a/core/play/src/main/scala/play/api/mvc/Flash.scala b/core/play/src/main/scala/play/api/mvc/Flash.scala index aadfa8d41ca..a9f6f6229be 100644 --- a/core/play/src/main/scala/play/api/mvc/Flash.scala +++ b/core/play/src/main/scala/play/api/mvc/Flash.scala @@ -21,6 +21,7 @@ import scala.annotation.varargs * Flash data are encoded into an HTTP cookie, and can only contain simple `String` values. */ case class Flash(data: Map[String, String] = Map.empty[String, String]) { + /** * Optionally returns the flash value associated with a key. */ diff --git a/core/play/src/main/scala/play/api/mvc/Handler.scala b/core/play/src/main/scala/play/api/mvc/Handler.scala index 2701b854947..8efce121461 100644 --- a/core/play/src/main/scala/play/api/mvc/Handler.scala +++ b/core/play/src/main/scala/play/api/mvc/Handler.scala @@ -18,6 +18,7 @@ import scala.annotation.tailrec trait Handler object Handler { + /** * Some handlers are built as a series of stages, with each stage returning * a new [[RequestHeader]] and another stage, until eventually a terminal @@ -55,6 +56,7 @@ object Handler { } object Stage { + /** * Create a `Stage` that modifies the request before calling the next handler. */ diff --git a/core/play/src/main/scala/play/api/mvc/Headers.scala b/core/play/src/main/scala/play/api/mvc/Headers.scala index 5b67236f012..709995708a3 100644 --- a/core/play/src/main/scala/play/api/mvc/Headers.scala +++ b/core/play/src/main/scala/play/api/mvc/Headers.scala @@ -22,6 +22,7 @@ import scala.collection.immutable.TreeSet * it lazily. */ class Headers(protected var _headers: Seq[(String, String)]) { + /** * The headers as a sequence of name-value pairs. */ @@ -127,6 +128,7 @@ class Headers(protected var _headers: Seq[(String, String)]) { } object Headers { + /** * For calling from Java. */ diff --git a/core/play/src/main/scala/play/api/mvc/MessagesRequest.scala b/core/play/src/main/scala/play/api/mvc/MessagesRequest.scala index 543e4fceb9d..2e087077b70 100644 --- a/core/play/src/main/scala/play/api/mvc/MessagesRequest.scala +++ b/core/play/src/main/scala/play/api/mvc/MessagesRequest.scala @@ -110,6 +110,7 @@ case class DefaultMessagesControllerComponents @Inject() ( * A base controller that returns a [[MessagesRequest]] as the base Action. */ trait MessagesBaseController extends BaseControllerHelpers { + /** * The components needed to use the controller methods */ diff --git a/core/play/src/main/scala/play/api/mvc/RangeResult.scala b/core/play/src/main/scala/play/api/mvc/RangeResult.scala index 026cf6c8212..46bae589802 100644 --- a/core/play/src/main/scala/play/api/mvc/RangeResult.scala +++ b/core/play/src/main/scala/play/api/mvc/RangeResult.scala @@ -288,6 +288,7 @@ private[mvc] object RangeSet { } object RangeResult { + /** * Stream inputStream using range headers. * diff --git a/core/play/src/main/scala/play/api/mvc/Render.scala b/core/play/src/main/scala/play/api/mvc/Render.scala index db60104f29a..511f6e91c0d 100644 --- a/core/play/src/main/scala/play/api/mvc/Render.scala +++ b/core/play/src/main/scala/play/api/mvc/Render.scala @@ -12,6 +12,7 @@ import play.core.Execution.Implicits.trampoline trait Rendering { object render { + /** * Tries to render the most acceptable result according to the request’s Accept header value. * {{{ diff --git a/core/play/src/main/scala/play/api/mvc/Request.scala b/core/play/src/main/scala/play/api/mvc/Request.scala index 2ad52807297..ce8c70ad10c 100644 --- a/core/play/src/main/scala/play/api/mvc/Request.scala +++ b/core/play/src/main/scala/play/api/mvc/Request.scala @@ -111,6 +111,7 @@ trait Request[+A] extends RequestHeader { } object Request { + /** * Create a new Request from a RequestHeader and a body. The RequestHeader's * methods aren't evaluated when this method is called. diff --git a/core/play/src/main/scala/play/api/mvc/RequestExtractors.scala b/core/play/src/main/scala/play/api/mvc/RequestExtractors.scala index 9d28b639bd0..e60ef761659 100644 --- a/core/play/src/main/scala/play/api/mvc/RequestExtractors.scala +++ b/core/play/src/main/scala/play/api/mvc/RequestExtractors.scala @@ -5,6 +5,7 @@ package play.api.mvc trait RequestExtractors extends AcceptExtractors { + /** * Convenient extractor allowing to apply two extractors. * Example of use: @@ -23,6 +24,7 @@ trait RequestExtractors extends AcceptExtractors { * Define a set of extractors allowing to pattern match on the Accept HTTP header of a request */ trait AcceptExtractors { + /** * Common extractors to check if a request accepts JSON, Html, etc. * Example of use: diff --git a/core/play/src/main/scala/play/api/mvc/Results.scala b/core/play/src/main/scala/play/api/mvc/Results.scala index c16305199e5..878fecab381 100644 --- a/core/play/src/main/scala/play/api/mvc/Results.scala +++ b/core/play/src/main/scala/play/api/mvc/Results.scala @@ -109,6 +109,7 @@ object ResponseHeader { } object Result { + /** * Logs a redirect warning for flashing (in dev mode) if the status code is not 3xx */ @@ -136,6 +137,7 @@ case class Result( newFlash: Option[Flash] = None, newCookies: Seq[Cookie] = Seq.empty ) { + /** * Adds headers to this result. * @@ -381,6 +383,7 @@ case class Codec(charset: String)(val encode: String => ByteString, val decode: * Default Codec support. */ object Codec { + /** * Create a Codec from an encoding already supported by the JVM. */ @@ -399,12 +402,14 @@ object Codec { } trait LegacyI18nSupport { + /** * Adds convenient methods to handle the client-side language. * * This class exists only for backward compatibility. */ implicit class ResultWithLang(result: Result)(implicit messagesApi: MessagesApi) { + /** * Sets the user's language permanently for future requests by storing it in a cookie. * @@ -502,6 +507,7 @@ trait Results { * @param status the HTTP response status, e.g ‘200 OK’ */ class Status(status: Int) extends Result(header = ResponseHeader(status), body = HttpEntity.NoEntity) { + /** * Set the result's content. * diff --git a/core/play/src/main/scala/play/api/mvc/Security.scala b/core/play/src/main/scala/play/api/mvc/Security.scala index e397804736e..c6a89664ff6 100644 --- a/core/play/src/main/scala/play/api/mvc/Security.scala +++ b/core/play/src/main/scala/play/api/mvc/Security.scala @@ -160,6 +160,7 @@ object Security { } object AuthenticatedBuilder { + /** * Create an authenticated builder * diff --git a/core/play/src/main/scala/play/api/mvc/Session.scala b/core/play/src/main/scala/play/api/mvc/Session.scala index c8831fe5746..1e7ea04e764 100644 --- a/core/play/src/main/scala/play/api/mvc/Session.scala +++ b/core/play/src/main/scala/play/api/mvc/Session.scala @@ -21,6 +21,7 @@ import scala.annotation.varargs * Session data are encoded into an HTTP cookie, and can only contain simple `String` values. */ case class Session(data: Map[String, String] = Map.empty) { + /** * Optionally returns the session value associated with a key. */ diff --git a/core/play/src/main/scala/play/api/mvc/WebSocket.scala b/core/play/src/main/scala/play/api/mvc/WebSocket.scala index 726ab983ae0..39dfe6e180e 100644 --- a/core/play/src/main/scala/play/api/mvc/WebSocket.scala +++ b/core/play/src/main/scala/play/api/mvc/WebSocket.scala @@ -22,6 +22,7 @@ import scala.util.control.NonFatal * A WebSocket handler. */ trait WebSocket extends Handler { + /** * Execute the WebSocket. * diff --git a/core/play/src/main/scala/play/api/mvc/request/Cell.scala b/core/play/src/main/scala/play/api/mvc/request/Cell.scala index 8e2c637ae28..58eb3b96fbd 100644 --- a/core/play/src/main/scala/play/api/mvc/request/Cell.scala +++ b/core/play/src/main/scala/play/api/mvc/request/Cell.scala @@ -11,6 +11,7 @@ package play.api.mvc.request * it is first needed. */ trait Cell[+A] { + /** * The value in the cell. Calling this method may force the value to be evaluated. */ @@ -26,6 +27,7 @@ trait Cell[+A] { } object Cell { + /** * Create a cell with the given value assigned to it. */ diff --git a/core/play/src/main/scala/play/api/mvc/request/RemoteConnection.scala b/core/play/src/main/scala/play/api/mvc/request/RemoteConnection.scala index 08d74948f55..e77ca084b00 100644 --- a/core/play/src/main/scala/play/api/mvc/request/RemoteConnection.scala +++ b/core/play/src/main/scala/play/api/mvc/request/RemoteConnection.scala @@ -15,6 +15,7 @@ import com.google.common.net.InetAddresses * to the request by an upstream proxy, e.g. `Forwarded` headers. */ trait RemoteConnection { + /** * The remote client's address. */ @@ -47,6 +48,7 @@ trait RemoteConnection { } object RemoteConnection { + /** * Create a RemoteConnection object. The address string is parsed lazily. */ diff --git a/core/play/src/main/scala/play/api/mvc/request/RequestAttrKey.scala b/core/play/src/main/scala/play/api/mvc/request/RequestAttrKey.scala index fb82d7d37b7..d11e8dcdbe0 100644 --- a/core/play/src/main/scala/play/api/mvc/request/RequestAttrKey.scala +++ b/core/play/src/main/scala/play/api/mvc/request/RequestAttrKey.scala @@ -13,6 +13,7 @@ import play.api.mvc.Session * Keys to request attributes. */ object RequestAttrKey { + /** * The key for the request attribute storing a request id. */ diff --git a/core/play/src/main/scala/play/api/mvc/request/RequestFactory.scala b/core/play/src/main/scala/play/api/mvc/request/RequestFactory.scala index 26915b207af..75512b056f3 100644 --- a/core/play/src/main/scala/play/api/mvc/request/RequestFactory.scala +++ b/core/play/src/main/scala/play/api/mvc/request/RequestFactory.scala @@ -16,6 +16,7 @@ import play.core.system.RequestIdProvider * A `RequestFactory` provides logic for creating requests. */ trait RequestFactory { + /** * Create a `RequestHeader`. */ @@ -63,6 +64,7 @@ trait RequestFactory { } object RequestFactory { + /** * A `RequestFactory` that creates a request with the arguments given, without * any additional modification. diff --git a/core/play/src/main/scala/play/api/mvc/request/RequestTarget.scala b/core/play/src/main/scala/play/api/mvc/request/RequestTarget.scala index e81c2a1d83d..9672d44ccf4 100644 --- a/core/play/src/main/scala/play/api/mvc/request/RequestTarget.scala +++ b/core/play/src/main/scala/play/api/mvc/request/RequestTarget.scala @@ -95,6 +95,7 @@ trait RequestTarget { } object RequestTarget { + /** * Create a new RequestTarget from the given values. */ diff --git a/core/play/src/main/scala/play/api/package.scala b/core/play/src/main/scala/play/api/package.scala index c03dec55838..f363e564073 100644 --- a/core/play/src/main/scala/play/api/package.scala +++ b/core/play/src/main/scala/play/api/package.scala @@ -11,6 +11,7 @@ package object play package play { + /** * Contains the public API for Scala developers. * diff --git a/core/play/src/main/scala/play/api/routing/JavascriptReverseRouter.scala b/core/play/src/main/scala/play/api/routing/JavascriptReverseRouter.scala index a6d2c72d581..3ad49cc9763 100644 --- a/core/play/src/main/scala/play/api/routing/JavascriptReverseRouter.scala +++ b/core/play/src/main/scala/play/api/routing/JavascriptReverseRouter.scala @@ -13,6 +13,7 @@ import play.twirl.api.JavaScript case class JavaScriptReverseRoute(name: String, f: String) object JavaScriptReverseRouter { + /** * Generates a JavaScript router. * diff --git a/core/play/src/main/scala/play/api/routing/Router.scala b/core/play/src/main/scala/play/api/routing/Router.scala index 91f3f32cd8b..9c1c5661395 100644 --- a/core/play/src/main/scala/play/api/routing/Router.scala +++ b/core/play/src/main/scala/play/api/routing/Router.scala @@ -69,6 +69,7 @@ trait Router { * Utilities for routing. */ object Router { + /** * The type of the routes partial function */ @@ -98,6 +99,7 @@ object Router { import play.api.mvc.RequestHeader implicit class WithHandlerDef(val request: RequestHeader) extends AnyVal { + /** * The [[HandlerDef]] representing the routes file entry (if any) on this request. */ @@ -117,6 +119,7 @@ object Router { * Request attributes used by the router. */ object Attrs { + /** * Key for the [[HandlerDef]] used to handle the request. */ @@ -184,6 +187,7 @@ class SimpleRouterImpl(routesProvider: => Router.Routes) extends SimpleRouter { } object SimpleRouter { + /** * Create a new simple router from the given routes */ diff --git a/core/play/src/main/scala/play/api/routing/sird/PathBindableExtractor.scala b/core/play/src/main/scala/play/api/routing/sird/PathBindableExtractor.scala index 3b8b45785b6..9fb537a552e 100644 --- a/core/play/src/main/scala/play/api/routing/sird/PathBindableExtractor.scala +++ b/core/play/src/main/scala/play/api/routing/sird/PathBindableExtractor.scala @@ -49,6 +49,7 @@ class PathBindableExtractor[T](implicit pb: PathBindable[T]) { * Extractors that bind types from paths using [[play.api.mvc.PathBindable]]. */ trait PathBindableExtractors { + /** * An int extractor. */ diff --git a/core/play/src/main/scala/play/api/routing/sird/RequestMethodExtractor.scala b/core/play/src/main/scala/play/api/routing/sird/RequestMethodExtractor.scala index edb4702cf28..b44e6efcf03 100644 --- a/core/play/src/main/scala/play/api/routing/sird/RequestMethodExtractor.scala +++ b/core/play/src/main/scala/play/api/routing/sird/RequestMethodExtractor.scala @@ -18,6 +18,7 @@ class RequestMethodExtractor private[sird] (method: String) { * Extractors that extract requests by method. */ trait RequestMethodExtractors { + /** * Extracts a GET request. */ diff --git a/core/play/src/main/scala/play/api/routing/sird/package.scala b/core/play/src/main/scala/play/api/routing/sird/package.scala index a5ad298775f..118ca1fb8b5 100644 --- a/core/play/src/main/scala/play/api/routing/sird/package.scala +++ b/core/play/src/main/scala/play/api/routing/sird/package.scala @@ -46,6 +46,7 @@ import scala.language.experimental.macros */ package object sird extends RequestMethodExtractors with PathBindableExtractors { implicit class UrlContext(sc: StringContext) { + /** * String interpolator for extracting parameters out of URL paths. * diff --git a/core/play/src/main/scala/play/api/templates/Templates.scala b/core/play/src/main/scala/play/api/templates/Templates.scala index b1bb3494fbe..056da08c950 100644 --- a/core/play/src/main/scala/play/api/templates/Templates.scala +++ b/core/play/src/main/scala/play/api/templates/Templates.scala @@ -13,6 +13,7 @@ import scala.compat.java8.OptionConverters._ /** Defines a magic helper for Play templates. */ object PlayMagic { + /** * Generates a set of valid HTML attributes. * diff --git a/core/play/src/main/scala/play/core/ApplicationProvider.scala b/core/play/src/main/scala/play/core/ApplicationProvider.scala index ca655b873d9..9f8d3815e09 100644 --- a/core/play/src/main/scala/play/core/ApplicationProvider.scala +++ b/core/play/src/main/scala/play/core/ApplicationProvider.scala @@ -28,6 +28,7 @@ trait SourceMapper { * Provides information about a Play Application running inside a Play server. */ trait ApplicationProvider { + /** * Get the application. In dev mode this lazily loads the application. * @@ -43,6 +44,7 @@ trait ApplicationProvider { } object ApplicationProvider { + /** * Creates an ApplicationProvider that wraps an Application instance. */ diff --git a/core/play/src/main/scala/play/core/j/HttpExecutionContext.scala b/core/play/src/main/scala/play/core/j/HttpExecutionContext.scala index 9942500ddbe..8a639f7582f 100644 --- a/core/play/src/main/scala/play/core/j/HttpExecutionContext.scala +++ b/core/play/src/main/scala/play/core/j/HttpExecutionContext.scala @@ -12,6 +12,7 @@ import scala.concurrent.ExecutionContext import scala.concurrent.ExecutionContextExecutor object HttpExecutionContext { + /** * Create an HttpExecutionContext with values from the current thread. */ diff --git a/core/play/src/main/scala/play/core/j/JavaAction.scala b/core/play/src/main/scala/play/core/j/JavaAction.scala index f50db0dede4..2bf92511931 100644 --- a/core/play/src/main/scala/play/core/j/JavaAction.scala +++ b/core/play/src/main/scala/play/core/j/JavaAction.scala @@ -188,6 +188,7 @@ abstract class JavaAction(val handlerComponents: JavaHandlerComponents) * the JavaComponents, will return a handler that can be invoked by a Play server. */ trait JavaHandler extends Handler { + /** * Return a Handler that has the necessary components supplied to execute it. */ diff --git a/core/play/src/main/scala/play/core/parsers/FormUrlEncodedParser.scala b/core/play/src/main/scala/play/core/parsers/FormUrlEncodedParser.scala index 28718727d90..eebb46b6da8 100644 --- a/core/play/src/main/scala/play/core/parsers/FormUrlEncodedParser.scala +++ b/core/play/src/main/scala/play/core/parsers/FormUrlEncodedParser.scala @@ -8,6 +8,7 @@ import java.net.URLDecoder /** An object for parsing application/x-www-form-urlencoded data */ object FormUrlEncodedParser { + /** * Parse the content type "application/x-www-form-urlencoded" which consists of a bunch of & separated key=value * pairs, both of which are URL encoded. diff --git a/core/play/src/main/scala/play/core/parsers/Multipart.scala b/core/play/src/main/scala/play/core/parsers/Multipart.scala index 6954f41bf6a..e5baee954df 100644 --- a/core/play/src/main/scala/play/core/parsers/Multipart.scala +++ b/core/play/src/main/scala/play/core/parsers/Multipart.scala @@ -394,17 +394,16 @@ object Multipart { headers match { case FileInfoMatcher(partName, fileName, contentType, dispositionType) => - checkEmptyBody(input, partStart, totalMemoryBufferSize)( - newInput => - handleFilePart( - newInput, - partStart, - totalMemoryBufferSize, - partName, - fileName, - contentType, - dispositionType - ) + checkEmptyBody(input, partStart, totalMemoryBufferSize)(newInput => + handleFilePart( + newInput, + partStart, + totalMemoryBufferSize, + partName, + fileName, + contentType, + dispositionType + ) )(newInput => handleBadPart(newInput, partStart, totalMemoryBufferSize, headers)) case PartInfoMatcher(name) => handleDataPart(input, partStart, memoryBufferSize + name.length, name) diff --git a/core/play/src/main/scala/play/core/routing/GeneratedRouter.scala b/core/play/src/main/scala/play/core/routing/GeneratedRouter.scala index fac6e781712..45a63945b29 100644 --- a/core/play/src/main/scala/play/core/routing/GeneratedRouter.scala +++ b/core/play/src/main/scala/play/core/routing/GeneratedRouter.scala @@ -17,6 +17,7 @@ import scala.collection.JavaConverters._ * A route */ object Route { + /** * Extractor of route from a request. */ diff --git a/core/play/src/main/scala/play/core/routing/HandlerInvoker.scala b/core/play/src/main/scala/play/core/routing/HandlerInvoker.scala index 1ed65c92c03..fa9e2ec890b 100644 --- a/core/play/src/main/scala/play/core/routing/HandlerInvoker.scala +++ b/core/play/src/main/scala/play/core/routing/HandlerInvoker.scala @@ -25,6 +25,7 @@ import scala.util.control.NonFatal * that thunk. Constructed by a `HandlerInvokerFactory`. */ trait HandlerInvoker[-T] { + /** * Create a `Handler` that wraps the given thunk. The thunk won't be called * until the `Handler` is applied. The returned Handler will be used by @@ -40,6 +41,7 @@ trait HandlerInvoker[-T] { */ @scala.annotation.implicitNotFound("Cannot use a method returning ${T} as a Handler for requests") trait HandlerInvokerFactory[-T] { + /** * Create an invoker for the given thunk that is never called. * @param fakeCall A simulated call to the controller method. Needed to diff --git a/core/play/src/main/scala/play/core/system/WebCommands.scala b/core/play/src/main/scala/play/core/system/WebCommands.scala index 5bef78a45ef..3e37aacc1a5 100644 --- a/core/play/src/main/scala/play/core/system/WebCommands.scala +++ b/core/play/src/main/scala/play/core/system/WebCommands.scala @@ -14,6 +14,7 @@ import scala.collection.mutable.ArrayBuffer * Handlers for web commands. */ trait WebCommands { + /** * Add a handler to be called on ApplicationProvider.handleWebCommand. */ diff --git a/core/play/src/main/scala/play/core/utils/AsciiSet.scala b/core/play/src/main/scala/play/core/utils/AsciiSet.scala index 91b04709502..ed411752dc4 100644 --- a/core/play/src/main/scala/play/core/utils/AsciiSet.scala +++ b/core/play/src/main/scala/play/core/utils/AsciiSet.scala @@ -7,6 +7,7 @@ package play.core.utils import java.util.{ BitSet => JBitSet } object AsciiSet { + /** Create a set of a single character. */ def apply(c: Char): AsciiChar = new AsciiChar(c) @@ -35,6 +36,7 @@ object AsciiSet { * using `toBitSet` for fast querying. */ trait AsciiSet { + /** * The internal method used to query for set membership. * Doesn't do any bounds checks. Also may be slow, so to @@ -65,6 +67,7 @@ private[play] final class AsciiRange(first: Int, last: Int) extends AsciiSet { private[utils] override def getInternal(i: Int): Boolean = i >= first && i <= last } private[play] object AsciiRange { + /** Helper to construct an [[AsciiRange]]. */ def apply(first: Int, last: Int): AsciiRange = new AsciiRange(first, last) } diff --git a/core/play/src/main/scala/play/core/utils/HttpHeaderEncoding.scala b/core/play/src/main/scala/play/core/utils/HttpHeaderEncoding.scala index dc9a984888b..830726d5302 100644 --- a/core/play/src/main/scala/play/core/utils/HttpHeaderEncoding.scala +++ b/core/play/src/main/scala/play/core/utils/HttpHeaderEncoding.scala @@ -107,20 +107,19 @@ private[play] object HttpHeaderParameterEncoding { // end up with multiple placeholders per logical character. value .codePoints() - .forEach( - codePoint => - // We could support a wider range of characters here by using - // the 'token' or 'quoted printable' encoding, however it's - // simpler to use the subset of characters that is also valid - // for extended attributes. - if (codePoint >= 0 && codePoint <= 255 && PartialQuotedText.get(codePoint)) { - builder.append(codePoint.toChar) - } else { - // Set flag because we need to render an extended parameter. - hasExtendedChars = true - // Render a placeholder instead of the unsupported character. - builder.append(PlaceholderChar) - } + .forEach(codePoint => + // We could support a wider range of characters here by using + // the 'token' or 'quoted printable' encoding, however it's + // simpler to use the subset of characters that is also valid + // for extended attributes. + if (codePoint >= 0 && codePoint <= 255 && PartialQuotedText.get(codePoint)) { + builder.append(codePoint.toChar) + } else { + // Set flag because we need to render an extended parameter. + hasExtendedChars = true + // Render a placeholder instead of the unsupported character. + builder.append(PlaceholderChar) + } ) builder.append('"') diff --git a/core/play/src/main/scala/play/server/api/SSLEngineProvider.scala b/core/play/src/main/scala/play/server/api/SSLEngineProvider.scala index beeef1dc3fd..adbdfb2df56 100644 --- a/core/play/src/main/scala/play/server/api/SSLEngineProvider.scala +++ b/core/play/src/main/scala/play/server/api/SSLEngineProvider.scala @@ -10,6 +10,7 @@ import javax.net.ssl.SSLEngine * To configure the SSLEngine used by Play as a server, extend this class. See more details in [[play.server.SSLEngineProvider]]. */ trait SSLEngineProvider extends play.server.SSLEngineProvider { + /** * @return the SSL engine to be used for HTTPS connection. */ diff --git a/core/play/src/main/scala/play/utils/InlineCache.scala b/core/play/src/main/scala/play/utils/InlineCache.scala index db64ca145fb..bac62e34316 100644 --- a/core/play/src/main/scala/play/utils/InlineCache.scala +++ b/core/play/src/main/scala/play/utils/InlineCache.scala @@ -39,6 +39,7 @@ import java.lang.ref.SoftReference * to be conservative. */ private[play] final class InlineCache[A <: AnyRef, B](f: A => B) extends (A => B) { + /** * For performance, don't synchronize this value. Instead, let * the cache be updated on different threads. If the input value diff --git a/core/play/src/main/scala/play/utils/Reflect.scala b/core/play/src/main/scala/play/utils/Reflect.scala index 797d8be0441..c5190119373 100644 --- a/core/play/src/main/scala/play/utils/Reflect.scala +++ b/core/play/src/main/scala/play/utils/Reflect.scala @@ -13,6 +13,7 @@ import play.api.PlayException import scala.reflect.ClassTag object Reflect { + /** * Lookup the given key from the given configuration, and provide bindings for the ScalaTrait to a class by that key. * diff --git a/core/play/src/main/scala/play/utils/Threads.scala b/core/play/src/main/scala/play/utils/Threads.scala index f114c185ad2..8ac649fe34b 100644 --- a/core/play/src/main/scala/play/utils/Threads.scala +++ b/core/play/src/main/scala/play/utils/Threads.scala @@ -8,6 +8,7 @@ package play.utils * provides helpers for managing ClassLoaders and Threads */ object Threads { + /** * executes given function in the context of the provided classloader * @param classloader that should be used to execute given function diff --git a/core/play/src/main/scala/play/utils/UriEncoding.scala b/core/play/src/main/scala/play/utils/UriEncoding.scala index 295c036b61c..11e18cb8ed8 100644 --- a/core/play/src/main/scala/play/utils/UriEncoding.scala +++ b/core/play/src/main/scala/play/utils/UriEncoding.scala @@ -17,6 +17,7 @@ import play.core.utils.AsciiSet * @define javadoc http://docs.oracle.com/javase/8/docs/api */ object UriEncoding { + /** * Encode a string so that it can be used safely in the "path segment" * part of a URI. A path segment is defined in RFC 3986. In a URI such diff --git a/core/play/src/main/scala/views/helper/Helpers.scala b/core/play/src/main/scala/views/helper/Helpers.scala index 76dcc95a685..3732cf2c817 100644 --- a/core/play/src/main/scala/views/helper/Helpers.scala +++ b/core/play/src/main/scala/views/helper/Helpers.scala @@ -80,6 +80,7 @@ package views.html.helper { } object repeat extends RepeatHelper { + /** * Render a field a repeated number of times. * @@ -96,6 +97,7 @@ package views.html.helper { } object repeatWithIndex extends RepeatHelper { + /** * Render a field a repeated number of times. * diff --git a/core/play/src/main/scala/views/html/helper/CSPNonce.scala b/core/play/src/main/scala/views/html/helper/CSPNonce.scala index 202ee7e9042..695e2f6bb93 100644 --- a/core/play/src/main/scala/views/html/helper/CSPNonce.scala +++ b/core/play/src/main/scala/views/html/helper/CSPNonce.scala @@ -14,6 +14,7 @@ import play.twirl.api.Html * @see [[play.api.mvc.request.RequestAttrKey.CSPNonce]] */ object CSPNonce { + /** * Gets nonce if RequestAttr.CSPNonce has a nonce value set. * diff --git a/core/play/src/main/scala/views/html/helper/package.scala b/core/play/src/main/scala/views/html/helper/package.scala index e5c21d492dc..7c97f403212 100644 --- a/core/play/src/main/scala/views/html/helper/package.scala +++ b/core/play/src/main/scala/views/html/helper/package.scala @@ -8,6 +8,7 @@ package views.html * Contains template helpers, for example for generating HTML forms. */ package object helper { + /** * Default input structure. * diff --git a/core/play/src/main/scala/views/js/helper/package.scala b/core/play/src/main/scala/views/js/helper/package.scala index 9fbf0c049ce..6999216b372 100644 --- a/core/play/src/main/scala/views/js/helper/package.scala +++ b/core/play/src/main/scala/views/js/helper/package.scala @@ -12,6 +12,7 @@ import play.twirl.api.JavaScript * Contains helpers intended to be used in JavaScript templates */ package object helper { + /** * Generates a JavaScript value from a Scala value. * diff --git a/core/play/src/main/scala/views/package.scala b/core/play/src/main/scala/views/package.scala index 6a93cda85fc..d7479730e5e 100644 --- a/core/play/src/main/scala/views/package.scala +++ b/core/play/src/main/scala/views/package.scala @@ -8,6 +8,7 @@ package object views package views { + /** * Contains ready to use built-in templates and template helpers for html templates. */ diff --git a/core/play/src/test/scala/play/api/ConfigurationSpec.scala b/core/play/src/test/scala/play/api/ConfigurationSpec.scala index f797993e916..7a6fa9e54b2 100644 --- a/core/play/src/test/scala/play/api/ConfigurationSpec.scala +++ b/core/play/src/test/scala/play/api/ConfigurationSpec.scala @@ -421,6 +421,7 @@ class ConfigurationSpec extends Specification { } object ConfigurationSpec { + /** Allows loading in-memory resources. */ final class InMemoryResourceClassLoader(entries: Map[String, String]) extends ClassLoader { val bytes = entries.mapValues(_.getBytes(StandardCharsets.UTF_8)).toMap diff --git a/core/play/src/test/scala/play/api/libs/TemporaryFileCreatorSpec.scala b/core/play/src/test/scala/play/api/libs/TemporaryFileCreatorSpec.scala index b4592b1172d..dc213e02e64 100644 --- a/core/play/src/test/scala/play/api/libs/TemporaryFileCreatorSpec.scala +++ b/core/play/src/test/scala/play/api/libs/TemporaryFileCreatorSpec.scala @@ -421,14 +421,15 @@ class TemporaryFileCreatorSpec extends Specification with Mockito { } val app = appLoader.load(context) Play.start(app) - val tempFile = try { - val tempFileCreator = app.injector.instanceOf[TemporaryFileCreator] - val tempFile = tempFileCreator.create() - tempFile.exists must beTrue - tempFile - } finally { - Play.stop(app) - } + val tempFile = + try { + val tempFileCreator = app.injector.instanceOf[TemporaryFileCreator] + val tempFile = tempFileCreator.create() + tempFile.exists must beTrue + tempFile + } finally { + Play.stop(app) + } tempFile.exists must beFalse } diff --git a/core/play/src/test/scala/play/api/mvc/MaxLengthBodyParserSpec.scala b/core/play/src/test/scala/play/api/mvc/MaxLengthBodyParserSpec.scala index 0fc9e6d3868..6322be744b1 100644 --- a/core/play/src/test/scala/play/api/mvc/MaxLengthBodyParserSpec.scala +++ b/core/play/src/test/scala/play/api/mvc/MaxLengthBodyParserSpec.scala @@ -56,15 +56,14 @@ class MaxLengthBodyParserSpec extends Specification with AfterAll { val parser = Accumulator( Sink .seq[ByteString] - .mapMaterializedValue( - future => - future.transform({ bytes => - bodyParsed.success(()) - Right(bytes.fold(ByteString.empty)(_ ++ _)) - }, { t => - bodyParsed.failure(t) - t - }) + .mapMaterializedValue(future => + future.transform({ bytes => + bodyParsed.success(()) + Right(bytes.fold(ByteString.empty)(_ ++ _)) + }, { t => + bodyParsed.failure(t) + t + }) ) ) (parser, bodyParsed.future) diff --git a/core/play/src/test/scala/play/core/test/Fakes.scala b/core/play/src/test/scala/play/core/test/Fakes.scala index db3bd057c56..2c7dafe8a03 100644 --- a/core/play/src/test/scala/play/core/test/Fakes.scala +++ b/core/play/src/test/scala/play/core/test/Fakes.scala @@ -155,6 +155,7 @@ object FakeRequest extends FakeRequestFactory(new DefaultRequestFactory(HttpConf * @param requestFactory Used to construct the wrapped requests. */ class FakeRequestFactory(requestFactory: RequestFactory) { + /** * Constructs a new GET / fake request. */ diff --git a/core/play/src/test/scala/play/core/test/package.scala b/core/play/src/test/scala/play/core/test/package.scala index f667207d516..d031519ad7e 100644 --- a/core/play/src/test/scala/play/core/test/package.scala +++ b/core/play/src/test/scala/play/core/test/package.scala @@ -11,6 +11,7 @@ import play.api.inject.DefaultApplicationLifecycle import play.api.routing.Router package object test { + /** * Run the given block of code with an application. */ diff --git a/dev-mode/play-docs-sbt-plugin/src/main/scala/com/typesafe/play/docs/sbtplugin/PlayDocsValidation.scala b/dev-mode/play-docs-sbt-plugin/src/main/scala/com/typesafe/play/docs/sbtplugin/PlayDocsValidation.scala index 7a92d472e2b..d50fbf11cd8 100644 --- a/dev-mode/play-docs-sbt-plugin/src/main/scala/com/typesafe/play/docs/sbtplugin/PlayDocsValidation.scala +++ b/dev-mode/play-docs-sbt-plugin/src/main/scala/com/typesafe/play/docs/sbtplugin/PlayDocsValidation.scala @@ -35,6 +35,7 @@ import Imports.PlayDocsKeys._ // Test that all the docs are renderable and valid object PlayDocsValidation extends PlayDocsValidationCompat { + /** * A report of all references from all markdown files. * diff --git a/dev-mode/routes-compiler/src/main/scala/play/routes/compiler/RoutesCompiler.scala b/dev-mode/routes-compiler/src/main/scala/play/routes/compiler/RoutesCompiler.scala index d0dc1f9e406..486b51d1022 100644 --- a/dev-mode/routes-compiler/src/main/scala/play/routes/compiler/RoutesCompiler.scala +++ b/dev-mode/routes-compiler/src/main/scala/play/routes/compiler/RoutesCompiler.scala @@ -23,6 +23,7 @@ object RoutesCompiler { * A source file that's been generated by the routes compiler */ trait GeneratedSource { + /** * The original source file associated with this generated source file, if known */ diff --git a/dev-mode/routes-compiler/src/main/scala/play/routes/compiler/RoutesFileParser.scala b/dev-mode/routes-compiler/src/main/scala/play/routes/compiler/RoutesFileParser.scala index 1085c095750..87b28b6c0e5 100644 --- a/dev-mode/routes-compiler/src/main/scala/play/routes/compiler/RoutesFileParser.scala +++ b/dev-mode/routes-compiler/src/main/scala/play/routes/compiler/RoutesFileParser.scala @@ -13,6 +13,7 @@ import scala.util.parsing.input._ import scala.language.postfixOps object RoutesFileParser { + /** * Parse the given routes file * diff --git a/dev-mode/routes-compiler/src/main/scala/play/routes/compiler/RoutesGenerator.scala b/dev-mode/routes-compiler/src/main/scala/play/routes/compiler/RoutesGenerator.scala index 985361c166a..d5ec06dc331 100644 --- a/dev-mode/routes-compiler/src/main/scala/play/routes/compiler/RoutesGenerator.scala +++ b/dev-mode/routes-compiler/src/main/scala/play/routes/compiler/RoutesGenerator.scala @@ -9,6 +9,7 @@ import java.io.File import play.routes.compiler.RoutesCompiler.RoutesCompilerTask trait RoutesGenerator { + /** * Generate a router * diff --git a/dev-mode/routes-compiler/src/main/scala/play/routes/compiler/RoutesModels.scala b/dev-mode/routes-compiler/src/main/scala/play/routes/compiler/RoutesModels.scala index 71d750c9e3e..cfec2cda61f 100644 --- a/dev-mode/routes-compiler/src/main/scala/play/routes/compiler/RoutesModels.scala +++ b/dev-mode/routes-compiler/src/main/scala/play/routes/compiler/RoutesModels.scala @@ -142,6 +142,7 @@ case class StaticPart(value: String) extends PathPart { * A complete path pattern, consisting of a sequence of path parts. */ case class PathPattern(parts: Seq[PathPart]) { + /** * Whether this path pattern has a parameter by the given name. */ diff --git a/dev-mode/routes-compiler/src/main/scala/play/routes/compiler/templates/package.scala b/dev-mode/routes-compiler/src/main/scala/play/routes/compiler/templates/package.scala index 3baf3cea5c4..65196e6f2a2 100644 --- a/dev-mode/routes-compiler/src/main/scala/play/routes/compiler/templates/package.scala +++ b/dev-mode/routes-compiler/src/main/scala/play/routes/compiler/templates/package.scala @@ -11,6 +11,7 @@ import scala.util.matching.Regex * Helper methods used in the templates */ package object templates { + /** * Mark lines with source map information. */ @@ -314,18 +315,17 @@ package object templates { */ def reverseSignature(routes: Seq[Route]): String = reverseParameters(routes) - .map( - p => - safeKeyword(p._1.name) + ":" + p._1.typeName + { - Option(routes.map(_.call.routeParams(p._2).default).distinct) - .filter(_.size == 1) - .flatMap(_.headOption) - .map { - case None => "" - case Some(default) => " = " + default - } - .getOrElse("") - } + .map(p => + safeKeyword(p._1.name) + ":" + p._1.typeName + { + Option(routes.map(_.call.routeParams(p._2).default).distinct) + .filter(_.size == 1) + .flatMap(_.headOption) + .map { + case None => "" + case Some(default) => " = " + default + } + .getOrElse("") + } ) .mkString(", ") diff --git a/dev-mode/run-support/src/main/scala/play/runsupport/RunHook.scala b/dev-mode/run-support/src/main/scala/play/runsupport/RunHook.scala index 86935887601..963e50878bf 100644 --- a/dev-mode/run-support/src/main/scala/play/runsupport/RunHook.scala +++ b/dev-mode/run-support/src/main/scala/play/runsupport/RunHook.scala @@ -12,6 +12,7 @@ import scala.util.control.NonFatal * apply startup/cleanup actions around a play application. */ trait RunHook { + /** * Called before the play application is started, * but after all "before run" tasks have been completed. @@ -44,6 +45,7 @@ case class RunHookCompositeThrowable(val throwables: Set[Throwable]) object RunHook { // A bit of a magic hack to clean up the PlayRun file implicit class RunHooksRunner(val hooks: Seq[RunHook]) extends AnyVal { + /** * Runs all the hooks in the sequence of hooks. * Reports last failure if any have failure. diff --git a/dev-mode/sbt-plugin/src/main/scala-sbt-0.13/play/sbt/PlayImportCompat.scala b/dev-mode/sbt-plugin/src/main/scala-sbt-0.13/play/sbt/PlayImportCompat.scala index 451a17b9226..cf0d04936ed 100644 --- a/dev-mode/sbt-plugin/src/main/scala-sbt-0.13/play/sbt/PlayImportCompat.scala +++ b/dev-mode/sbt-plugin/src/main/scala-sbt-0.13/play/sbt/PlayImportCompat.scala @@ -17,6 +17,7 @@ import sbt.State * Fix compatibility issues for PlayImport. This is the version compatible with sbt 0.13. */ private[sbt] trait PlayImportCompat { + /** * Add this to your build.sbt, eg: * diff --git a/dev-mode/sbt-plugin/src/main/scala/play/sbt/PlayInteractionMode.scala b/dev-mode/sbt-plugin/src/main/scala/play/sbt/PlayInteractionMode.scala index 6a57bb993b6..38d3f1f098b 100644 --- a/dev-mode/sbt-plugin/src/main/scala/play/sbt/PlayInteractionMode.scala +++ b/dev-mode/sbt-plugin/src/main/scala/play/sbt/PlayInteractionMode.scala @@ -14,6 +14,7 @@ import scala.annotation.tailrec import scala.concurrent.duration._ trait PlayInteractionMode { + /** * This is our means of blocking a `play run` call until * the user has denoted, via some interface (console or GUI) that diff --git a/persistence/play-jdbc-api/src/main/scala/play/api/db/DBApi.scala b/persistence/play-jdbc-api/src/main/scala/play/api/db/DBApi.scala index 909088c9ef4..ea0e3459a63 100644 --- a/persistence/play-jdbc-api/src/main/scala/play/api/db/DBApi.scala +++ b/persistence/play-jdbc-api/src/main/scala/play/api/db/DBApi.scala @@ -8,6 +8,7 @@ package play.api.db * DB API for managing application databases. */ trait DBApi { + /** * All configured databases. */ diff --git a/persistence/play-jdbc-api/src/main/scala/play/api/db/Database.scala b/persistence/play-jdbc-api/src/main/scala/play/api/db/Database.scala index 93e885968d5..8ee2f4937a7 100644 --- a/persistence/play-jdbc-api/src/main/scala/play/api/db/Database.scala +++ b/persistence/play-jdbc-api/src/main/scala/play/api/db/Database.scala @@ -12,6 +12,7 @@ import javax.sql.DataSource * Database API. */ trait Database { + /** * The configuration name for this database. */ diff --git a/persistence/play-jdbc-evolutions/src/main/scala/play/api/db/evolutions/Evolutions.scala b/persistence/play-jdbc-evolutions/src/main/scala/play/api/db/evolutions/Evolutions.scala index 0b0084926f9..e7a44aaa2bb 100644 --- a/persistence/play-jdbc-evolutions/src/main/scala/play/api/db/evolutions/Evolutions.scala +++ b/persistence/play-jdbc-evolutions/src/main/scala/play/api/db/evolutions/Evolutions.scala @@ -32,6 +32,7 @@ import play.utils.PlayIO * @param sql_down the SQL statements for DOWN application */ case class Evolution(revision: Int, sql_up: String = "", sql_down: String = "") { + /** * Revision hash, automatically computed from the SQL content. */ @@ -42,6 +43,7 @@ case class Evolution(revision: Int, sql_up: String = "", sql_down: String = "") * A Script to run on the database. */ trait Script { + /** * Original evolution. */ diff --git a/persistence/play-jdbc-evolutions/src/main/scala/play/api/db/evolutions/EvolutionsApi.scala b/persistence/play-jdbc-evolutions/src/main/scala/play/api/db/evolutions/EvolutionsApi.scala index f6c8a001980..4eefbec83b7 100644 --- a/persistence/play-jdbc-evolutions/src/main/scala/play/api/db/evolutions/EvolutionsApi.scala +++ b/persistence/play-jdbc-evolutions/src/main/scala/play/api/db/evolutions/EvolutionsApi.scala @@ -27,6 +27,7 @@ import scala.util.control.NonFatal * Evolutions API. */ trait EvolutionsApi { + /** * Create evolution scripts. * @@ -437,6 +438,7 @@ private object DefaultEvolutionsApi { * Reader for evolutions */ trait EvolutionsReader { + /** * Read the evolutions for the given db */ @@ -447,6 +449,7 @@ trait EvolutionsReader { * Evolutions reader that reads evolutions from resources, for example, the file system or the classpath */ abstract class ResourceEvolutionsReader extends EvolutionsReader { + /** * Load the evolutions resource for the given database and revision. * @@ -563,6 +566,7 @@ class ClassLoaderEvolutionsReader( * Evolutions reader that reads evolution files from a class loader. */ object ClassLoaderEvolutionsReader { + /** * Create a class loader evolutions reader for the given prefix. */ @@ -587,6 +591,7 @@ class SimpleEvolutionsReader(evolutionsMap: Map[String, Seq[Evolution]]) extends * Simple map based implementation of the evolutions reader. */ object SimpleEvolutionsReader { + /** * Create a simple evolutions reader from the given data. * diff --git a/persistence/play-jdbc/src/main/scala/play/api/db/ConnectionPool.scala b/persistence/play-jdbc/src/main/scala/play/api/db/ConnectionPool.scala index 5ac516cdf8c..aef72960497 100644 --- a/persistence/play-jdbc/src/main/scala/play/api/db/ConnectionPool.scala +++ b/persistence/play-jdbc/src/main/scala/play/api/db/ConnectionPool.scala @@ -18,6 +18,7 @@ import play.utils.Reflect * Connection pool API for managing data sources. */ trait ConnectionPool { + /** * Create a data source with the given configuration. * @@ -36,6 +37,7 @@ trait ConnectionPool { } object ConnectionPool { + /** * Load a connection pool from a configured connection pool */ diff --git a/persistence/play-jdbc/src/main/scala/play/api/db/DBModule.scala b/persistence/play-jdbc/src/main/scala/play/api/db/DBModule.scala index d8d9b7e8d02..7b4fb32da4f 100644 --- a/persistence/play-jdbc/src/main/scala/play/api/db/DBModule.scala +++ b/persistence/play-jdbc/src/main/scala/play/api/db/DBModule.scala @@ -78,9 +78,8 @@ class DBApiProvider( val config = configuration.underlying val dbKey = config.getString("play.db.config") val pool = maybeInjector - .map( - injector => - ConnectionPool.fromConfig(config.getString("play.db.pool"), injector, environment, defaultConnectionPool) + .map(injector => + ConnectionPool.fromConfig(config.getString("play.db.pool"), injector, environment, defaultConnectionPool) ) .getOrElse(ConnectionPool.fromConfig(config.getString("play.db.pool"), environment, defaultConnectionPool)) val configs = if (config.hasPath(dbKey)) { diff --git a/persistence/play-jdbc/src/main/scala/play/api/db/Databases.scala b/persistence/play-jdbc/src/main/scala/play/api/db/Databases.scala index c712835907f..1413787a565 100644 --- a/persistence/play-jdbc/src/main/scala/play/api/db/Databases.scala +++ b/persistence/play-jdbc/src/main/scala/play/api/db/Databases.scala @@ -22,6 +22,7 @@ import scala.util.control.NonFatal * Creation helpers for manually instantiating databases. */ object Databases { + /** * Create a pooled database named "default" with the given driver and url. * diff --git a/project/BuildSettings.scala b/project/BuildSettings.scala index b33238a2eb8..e4c622ef15d 100644 --- a/project/BuildSettings.scala +++ b/project/BuildSettings.scala @@ -144,11 +144,10 @@ object BuildSettings { // Maps JDK 1.8 jar into apidoc. val rtJar = sys.props .get("sun.boot.class.path") - .flatMap( - cp => - cp.split(java.io.File.pathSeparator).collectFirst { - case str if str.endsWith(java.io.File.separator + "rt.jar") => str - } + .flatMap(cp => + cp.split(java.io.File.pathSeparator).collectFirst { + case str if str.endsWith(java.io.File.separator + "rt.jar") => str + } ) rtJar match { case None => Map.empty diff --git a/project/Dependencies.scala b/project/Dependencies.scala index 953e431b3d0..884bcb38c76 100644 --- a/project/Dependencies.scala +++ b/project/Dependencies.scala @@ -322,6 +322,7 @@ object AkkaDependency { val akkaRepository = uri(akkaSourceDependencyUri) implicit class RichProject(project: Project) { + /** Adds either a source or a binary dependency, depending on whether the above settings are set */ def addAkkaModuleDependency(module: String, config: String = ""): Project = if (shouldUseSourceDependency) { diff --git a/project/Docs.scala b/project/Docs.scala index e2e0819d198..283c8b25ffe 100644 --- a/project/Docs.scala +++ b/project/Docs.scala @@ -275,10 +275,9 @@ object Docs { .get(structure.data) .map(_.map { resources => (for { - conf <- resources.filter( - resource => - resource.name == "reference.conf" || resource.name.endsWith(".xml") || resource.name - .endsWith(".default") + conf <- resources.filter(resource => + resource.name == "reference.conf" || resource.name.endsWith(".xml") || resource.name + .endsWith(".default") ) id <- projectId.toSeq } yield id -> conf).distinct diff --git a/testkit/play-test/src/main/scala/play/api/test/ApplicationFactory.scala b/testkit/play-test/src/main/scala/play/api/test/ApplicationFactory.scala index efa25bd6d98..b6fc74bbc80 100644 --- a/testkit/play-test/src/main/scala/play/api/test/ApplicationFactory.scala +++ b/testkit/play-test/src/main/scala/play/api/test/ApplicationFactory.scala @@ -15,6 +15,7 @@ import play.api.routing.Router * Creates an [[Application]]. Usually created by a helper in [[ApplicationFactories]]. */ @ApiMayChange trait ApplicationFactory { + /** Creates an [[Application]]. */ def create(): Application } diff --git a/testkit/play-test/src/main/scala/play/api/test/Fakes.scala b/testkit/play-test/src/main/scala/play/api/test/Fakes.scala index 8709cfdaae0..3409cdfc1f7 100644 --- a/testkit/play-test/src/main/scala/play/api/test/Fakes.scala +++ b/testkit/play-test/src/main/scala/play/api/test/Fakes.scala @@ -151,6 +151,7 @@ object FakeRequest extends FakeRequestFactory(new DefaultRequestFactory(HttpConf * @param requestFactory Used to construct the wrapped requests. */ class FakeRequestFactory(requestFactory: RequestFactory) { + /** * Constructs a new GET / fake request. */ diff --git a/testkit/play-test/src/main/scala/play/api/test/Helpers.scala b/testkit/play-test/src/main/scala/play/api/test/Helpers.scala index 3b8457e4ade..36a43a0734a 100644 --- a/testkit/play-test/src/main/scala/play/api/test/Helpers.scala +++ b/testkit/play-test/src/main/scala/play/api/test/Helpers.scala @@ -159,6 +159,7 @@ trait PlayRunners extends HttpVerbs { } object PlayRunners { + /** * This mutex is used to ensure that no two tests that set the global application can run at the same time. */ @@ -197,6 +198,7 @@ trait Writeables { } trait DefaultAwaitTimeout { + /** * The default await timeout. Override this to change it. */ @@ -503,6 +505,7 @@ trait ResultExtractors { } trait StubPlayBodyParsersFactory { + /** * Stub method for unit testing, using NoTemporaryFileCreator. * @@ -516,6 +519,7 @@ trait StubPlayBodyParsersFactory { } trait StubMessagesFactory { + /** * @return a stub Langs * @param availables default as Seq(Lang.defaultLang). @@ -589,6 +593,7 @@ trait StubMessagesFactory { } trait StubBodyParserFactory { + /** * Stub method that returns the content immediately. Useful for unit testing. * @@ -608,6 +613,7 @@ trait StubControllerComponentsFactory extends StubPlayBodyParsersFactory with StubBodyParserFactory with StubMessagesFactory { + /** * Create a minimal controller components, useful for unit testing. * diff --git a/testkit/play-test/src/main/scala/play/api/test/Selenium.scala b/testkit/play-test/src/main/scala/play/api/test/Selenium.scala index 7bc50918ce4..566636cd368 100644 --- a/testkit/play-test/src/main/scala/play/api/test/Selenium.scala +++ b/testkit/play-test/src/main/scala/play/api/test/Selenium.scala @@ -100,6 +100,7 @@ case class TestBrowser(webDriver: WebDriver, baseUrl: Option[String]) extends Fl * Helper utilities to build TestBrowsers */ object TestBrowser { + /** * Creates an in-memory WebBrowser (using HtmlUnit) * @@ -124,6 +125,7 @@ object TestBrowser { } object WebDriverFactory { + /** * Creates a Selenium Web Driver and configures it * @param clazz Type of driver to create diff --git a/testkit/play-test/src/main/scala/play/api/test/ServerEndpointRecipe.scala b/testkit/play-test/src/main/scala/play/api/test/ServerEndpointRecipe.scala index ed026a0fe98..6441c3fe802 100644 --- a/testkit/play-test/src/main/scala/play/api/test/ServerEndpointRecipe.scala +++ b/testkit/play-test/src/main/scala/play/api/test/ServerEndpointRecipe.scala @@ -22,6 +22,7 @@ import play.core.server.ServerProvider * @see [[ServerEndpointRecipe.withEndpoint()]] */ @ApiMayChange sealed trait ServerEndpointRecipe { + /** A human-readable description of this endpoint. */ def description: String @@ -149,6 +150,7 @@ import play.core.server.ServerProvider } @ApiMayChange object ServerEndpointRecipe { + /** * Starts a server by following a [[ServerEndpointRecipe]] and using the * application provided by an [[ApplicationFactory]]. The server's endpoint diff --git a/testkit/play-test/src/main/scala/play/api/test/TestServer.scala b/testkit/play-test/src/main/scala/play/api/test/TestServer.scala index e83675b610a..e57f79144a3 100644 --- a/testkit/play-test/src/main/scala/play/api/test/TestServer.scala +++ b/testkit/play-test/src/main/scala/play/api/test/TestServer.scala @@ -86,6 +86,7 @@ case class TestServer(config: ServerConfig, application: Application, serverProv } object TestServer { + /** * A test web server. * diff --git a/testkit/play-test/src/main/scala/play/api/test/package.scala b/testkit/play-test/src/main/scala/play/api/test/package.scala index a320d084a1e..69bd22ab175 100644 --- a/testkit/play-test/src/main/scala/play/api/test/package.scala +++ b/testkit/play-test/src/main/scala/play/api/test/package.scala @@ -8,6 +8,7 @@ package play.api * Contains test helpers. */ package object test { + /** * Provided as an implicit by WithServer and WithBrowser. */ diff --git a/transport/client/play-ahc-ws/src/main/scala/play/api/libs/ws/ahc/AhcWSClient.scala b/transport/client/play-ahc-ws/src/main/scala/play/api/libs/ws/ahc/AhcWSClient.scala index 284818cbc33..6c56cd854a9 100644 --- a/transport/client/play-ahc-ws/src/main/scala/play/api/libs/ws/ahc/AhcWSClient.scala +++ b/transport/client/play-ahc-ws/src/main/scala/play/api/libs/ws/ahc/AhcWSClient.scala @@ -15,6 +15,7 @@ import play.api.libs.ws.WSRequest * See https://www.playframework.com/documentation/latest/ScalaWS for documentation. */ class AhcWSClient(underlyingClient: StandaloneAhcWSClient) extends WSClient { + /** * The underlying implementation of the client, if any. You must cast explicitly to the type you want. * diff --git a/transport/client/play-ahc-ws/src/main/scala/play/api/test/WSTestClient.scala b/transport/client/play-ahc-ws/src/main/scala/play/api/test/WSTestClient.scala index a6b6c66eddc..5592f5a040e 100644 --- a/transport/client/play-ahc-ws/src/main/scala/play/api/test/WSTestClient.scala +++ b/transport/client/play-ahc-ws/src/main/scala/play/api/test/WSTestClient.scala @@ -190,16 +190,15 @@ object WsTestClient extends WsTestClient { case None => // idleCheckTask = Option { - scheduler.scheduleAtFixedRate(initialDelay = idleDuration, interval = idleDuration)( - () => - if (references.size() == 0) { - logger.debug(s"check: no references found on client $client, system $system") - idleCheckTask.map(_.cancel()) - idleCheckTask = None - closeIdleResources(client, system) - } else { - logger.debug(s"check: client references = ${references.toArray.toSeq}") - } + scheduler.scheduleAtFixedRate(initialDelay = idleDuration, interval = idleDuration)(() => + if (references.size() == 0) { + logger.debug(s"check: no references found on client $client, system $system") + idleCheckTask.map(_.cancel()) + idleCheckTask = None + closeIdleResources(client, system) + } else { + logger.debug(s"check: client references = ${references.toArray.toSeq}") + } )(system.dispatcher) } } diff --git a/transport/client/play-ws/src/main/scala/play/api/libs/ws/WSClient.scala b/transport/client/play-ws/src/main/scala/play/api/libs/ws/WSClient.scala index bec50b983a7..a85eff643cd 100644 --- a/transport/client/play-ws/src/main/scala/play/api/libs/ws/WSClient.scala +++ b/transport/client/play-ws/src/main/scala/play/api/libs/ws/WSClient.scala @@ -21,6 +21,7 @@ import java.io.IOException * Please see the documentation at https://www.playframework.com/documentation/latest/ScalaWS for more details. */ trait WSClient extends Closeable { + /** * The underlying implementation of the client, if any. You must cast explicitly to the type you want. * @tparam T the type you are expecting (i.e. isInstanceOf) diff --git a/transport/client/play-ws/src/main/scala/play/api/libs/ws/WSResponse.scala b/transport/client/play-ws/src/main/scala/play/api/libs/ws/WSResponse.scala index e51a8b74633..78fd2ab934b 100644 --- a/transport/client/play-ws/src/main/scala/play/api/libs/ws/WSResponse.scala +++ b/transport/client/play-ws/src/main/scala/play/api/libs/ws/WSResponse.scala @@ -16,6 +16,7 @@ import scala.xml.Elem * A WS Response that can use Play specific classes. */ trait WSResponse extends StandaloneWSResponse with WSBodyReadables { + /** * The response status code. */ diff --git a/transport/server/play-akka-http-server/src/main/scala/akka/http/play/WebSocketHandler.scala b/transport/server/play-akka-http-server/src/main/scala/akka/http/play/WebSocketHandler.scala index 6ef3f8fff82..d670b036141 100644 --- a/transport/server/play-akka-http-server/src/main/scala/akka/http/play/WebSocketHandler.scala +++ b/transport/server/play-akka-http-server/src/main/scala/akka/http/play/WebSocketHandler.scala @@ -21,6 +21,7 @@ import play.core.server.common.WebSocketFlowHandler.MessageType import play.core.server.common.WebSocketFlowHandler.RawMessage object WebSocketHandler { + /** * Handle a WebSocket without selecting a subprotocol * diff --git a/transport/server/play-akka-http-server/src/main/scala/play/core/server/AkkaHttpServer.scala b/transport/server/play-akka-http-server/src/main/scala/play/core/server/AkkaHttpServer.scala index cf00d2e5d83..35310fd9f81 100644 --- a/transport/server/play-akka-http-server/src/main/scala/play/core/server/AkkaHttpServer.scala +++ b/transport/server/play-akka-http-server/src/main/scala/play/core/server/AkkaHttpServer.scala @@ -180,24 +180,25 @@ class AkkaHttpServer(context: AkkaHttpServer.Context) extends Server { secure: Boolean ): Http.ServerBinding = { // TODO: pass in Inet.SocketOption and LoggerAdapter params? - val bindingFuture: Future[Http.ServerBinding] = try { - Http() - .bindAndHandleAsync( - handler = handleRequest(_, connectionContext.isSecure), - interface = context.config.address, - port = port, - connectionContext = connectionContext, - settings = createServerSettings(port, connectionContext, secure) - ) - } catch { - // Http2SupportNotPresentException is private[akka] so we need to match the name - case e: Throwable if e.getClass.getSimpleName == "Http2SupportNotPresentException" => - throw new RuntimeException( - "HTTP/2 enabled but akka-http2-support not found. " + - "Add .enablePlugins(PlayAkkaHttp2Support) in build.sbt", - e - ) - } + val bindingFuture: Future[Http.ServerBinding] = + try { + Http() + .bindAndHandleAsync( + handler = handleRequest(_, connectionContext.isSecure), + interface = context.config.address, + port = port, + connectionContext = connectionContext, + settings = createServerSettings(port, connectionContext, secure) + ) + } catch { + // Http2SupportNotPresentException is private[akka] so we need to match the name + case e: Throwable if e.getClass.getSimpleName == "Http2SupportNotPresentException" => + throw new RuntimeException( + "HTTP/2 enabled but akka-http2-support not found. " + + "Add .enablePlugins(PlayAkkaHttp2Support) in build.sbt", + e + ) + } Await.result(bindingFuture, bindTimeout) } @@ -206,27 +207,27 @@ class AkkaHttpServer(context: AkkaHttpServer.Context) extends Server { private lazy val sslContext: SSLContext = ServerSSLEngine.createSSLEngineProvider(context.config, applicationProvider).sslContext() - private val httpServerBinding = context.config.port.map( - port => - createServerBinding( - port, - HttpConnectionContext(http2 = if (http2AlwaysForInsecure) Always else Never), - secure = false - ) + private val httpServerBinding = context.config.port.map(port => + createServerBinding( + port, + HttpConnectionContext(http2 = if (http2AlwaysForInsecure) Always else Never), + secure = false + ) ) private val httpsServerBinding = context.config.sslPort.map { port => - val connectionContext = try { - val clientAuth: Option[TLSClientAuth] = createClientAuth() - ConnectionContext.https( - sslContext = sslContext, - clientAuth = clientAuth - ) - } catch { - case NonFatal(e) => - logger.error(s"Cannot load SSL context", e) - ConnectionContext.noEncryption() - } + val connectionContext = + try { + val clientAuth: Option[TLSClientAuth] = createClientAuth() + ConnectionContext.https( + sslContext = sslContext, + clientAuth = clientAuth + ) + } catch { + case NonFatal(e) => + logger.error(s"Cannot load SSL context", e) + ConnectionContext.noEncryption() + } createServerBinding(port, connectionContext, secure = true) } @@ -367,16 +368,15 @@ class AkkaHttpServer(context: AkkaHttpServer.Context) extends Server { case (websocket: WebSocket, None) => // WebSocket handler for non WebSocket request logger.trace(s"Bad websocket request: $request") - val action = EssentialAction( - _ => - Accumulator.done( - Results - .Status(Status.UPGRADE_REQUIRED)("Upgrade to WebSocket required") - .withHeaders( - HeaderNames.UPGRADE -> "websocket", - HeaderNames.CONNECTION -> HeaderNames.UPGRADE - ) - ) + val action = EssentialAction(_ => + Accumulator.done( + Results + .Status(Status.UPGRADE_REQUIRED)("Upgrade to WebSocket required") + .withHeaders( + HeaderNames.UPGRADE -> "websocket", + HeaderNames.CONNECTION -> HeaderNames.UPGRADE + ) + ) ) runAction(tryApp, request, taggedRequestHeader, requestBodySource, action, errorHandler) case (akkaHttpHandler: AkkaHttpHandler, _) => @@ -489,62 +489,58 @@ class AkkaHttpServer(context: AkkaHttpServer.Context) extends Server { private lazy val Http1Plain = httpServerBinding .map(_.localAddress) - .map( - address => - ServerEndpoint( - description = "Akka HTTP HTTP/1.1 (plaintext)", - scheme = "http", - host = context.config.address, - port = address.getPort, - protocols = Set(PlayHttpProtocol.HTTP_1_0, PlayHttpProtocol.HTTP_1_1), - serverAttribute = serverHeaderConfig, - ssl = None - ) + .map(address => + ServerEndpoint( + description = "Akka HTTP HTTP/1.1 (plaintext)", + scheme = "http", + host = context.config.address, + port = address.getPort, + protocols = Set(PlayHttpProtocol.HTTP_1_0, PlayHttpProtocol.HTTP_1_1), + serverAttribute = serverHeaderConfig, + ssl = None + ) ) private lazy val Http1Encrypted = httpsServerBinding .map(_.localAddress) - .map( - address => - ServerEndpoint( - description = "Akka HTTP HTTP/1.1 (encrypted)", - scheme = "https", - host = context.config.address, - port = address.getPort, - protocols = Set(PlayHttpProtocol.HTTP_1_0, PlayHttpProtocol.HTTP_1_1), - serverAttribute = serverHeaderConfig, - ssl = Option(sslContext) - ) + .map(address => + ServerEndpoint( + description = "Akka HTTP HTTP/1.1 (encrypted)", + scheme = "https", + host = context.config.address, + port = address.getPort, + protocols = Set(PlayHttpProtocol.HTTP_1_0, PlayHttpProtocol.HTTP_1_1), + serverAttribute = serverHeaderConfig, + ssl = Option(sslContext) + ) ) private lazy val Http2Plain = httpServerBinding .map(_.localAddress) - .map( - address => - ServerEndpoint( - description = "Akka HTTP HTTP/2 (plaintext)", - scheme = "http", - host = context.config.address, - port = address.getPort, - protocols = Set(PlayHttpProtocol.HTTP_2_0), - serverAttribute = serverHeaderConfig, - ssl = None - ) + .map(address => + ServerEndpoint( + description = "Akka HTTP HTTP/2 (plaintext)", + scheme = "http", + host = context.config.address, + port = address.getPort, + protocols = Set(PlayHttpProtocol.HTTP_2_0), + serverAttribute = serverHeaderConfig, + ssl = None + ) ) private lazy val Http2Encrypted = httpsServerBinding .map(_.localAddress) - .map( - address => - ServerEndpoint( - description = "Akka HTTP HTTP/2 (encrypted)", - scheme = "https", - host = context.config.address, - port = address.getPort, - protocols = Set(PlayHttpProtocol.HTTP_1_0, PlayHttpProtocol.HTTP_1_1, PlayHttpProtocol.HTTP_2_0), - serverAttribute = serverHeaderConfig, - ssl = Option(sslContext) - ) + .map(address => + ServerEndpoint( + description = "Akka HTTP HTTP/2 (encrypted)", + scheme = "https", + host = context.config.address, + port = address.getPort, + protocols = Set(PlayHttpProtocol.HTTP_1_0, PlayHttpProtocol.HTTP_1_1, PlayHttpProtocol.HTTP_2_0), + serverAttribute = serverHeaderConfig, + ssl = Option(sslContext) + ) ) override val serverEndpoints: ServerEndpoints = { @@ -593,6 +589,7 @@ object AkkaHttpServer extends ServerFromRouter { ) object Context { + /** * Create a `Context` object from several common components. */ diff --git a/transport/server/play-akka-http-server/src/main/scala/play/core/server/akkahttp/AkkaModelConversion.scala b/transport/server/play-akka-http-server/src/main/scala/play/core/server/akkahttp/AkkaModelConversion.scala index 2f6b89c18e4..ec91a51f9d3 100644 --- a/transport/server/play-akka-http-server/src/main/scala/play/core/server/akkahttp/AkkaModelConversion.scala +++ b/transport/server/play-akka-http-server/src/main/scala/play/core/server/akkahttp/AkkaModelConversion.scala @@ -392,11 +392,10 @@ final case class AkkaHeadersWrapper( override def remove(keys: String*): Headers = copy( - hs = hs.filterNot( - h => - keys.exists { rm => - h.is(rm.toLowerCase(Locale.ROOT)) - } + hs = hs.filterNot(h => + keys.exists { rm => + h.is(rm.toLowerCase(Locale.ROOT)) + } ) ) diff --git a/transport/server/play-akka-http-server/src/main/scala/play/core/server/akkahttp/HttpRequestDecoder.scala b/transport/server/play-akka-http-server/src/main/scala/play/core/server/akkahttp/HttpRequestDecoder.scala index 37900de8134..986fc55ac70 100644 --- a/transport/server/play-akka-http-server/src/main/scala/play/core/server/akkahttp/HttpRequestDecoder.scala +++ b/transport/server/play-akka-http-server/src/main/scala/play/core/server/akkahttp/HttpRequestDecoder.scala @@ -17,6 +17,7 @@ import akka.util.ByteString * `Content-Encoding` is set. */ private[server] object HttpRequestDecoder { + /** * Decode the request with a decoder. Remove the `Content-Encoding` header * since the body will no longer be encoded. diff --git a/transport/server/play-netty-server/src/main/scala/play/core/server/NettyServer.scala b/transport/server/play-netty-server/src/main/scala/play/core/server/NettyServer.scala index 4071cadcff2..975e0abc06b 100644 --- a/transport/server/play-netty-server/src/main/scala/play/core/server/NettyServer.scala +++ b/transport/server/play-netty-server/src/main/scala/play/core/server/NettyServer.scala @@ -332,32 +332,30 @@ class NettyServer( private lazy val Http1Plain = httpChannel .map(_.localAddress().asInstanceOf[InetSocketAddress]) - .map( - address => - ServerEndpoint( - description = "Netty HTTP/1.1 (plaintext)", - scheme = "http", - host = config.address, - port = address.getPort, - protocols = Set(HttpProtocol.HTTP_1_0, HttpProtocol.HTTP_1_1), - serverAttribute = serverHeader, - ssl = None - ) + .map(address => + ServerEndpoint( + description = "Netty HTTP/1.1 (plaintext)", + scheme = "http", + host = config.address, + port = address.getPort, + protocols = Set(HttpProtocol.HTTP_1_0, HttpProtocol.HTTP_1_1), + serverAttribute = serverHeader, + ssl = None + ) ) private lazy val Http1Encrypted = httpsChannel .map(_.localAddress().asInstanceOf[InetSocketAddress]) - .map( - address => - ServerEndpoint( - description = "Netty HTTP/1.1 (encrypted)", - scheme = "https", - host = config.address, - port = address.getPort, - protocols = Set(HttpProtocol.HTTP_1_0, HttpProtocol.HTTP_1_1), - serverAttribute = serverHeader, - ssl = sslEngineProvider.map(_.sslContext()) - ) + .map(address => + ServerEndpoint( + description = "Netty HTTP/1.1 (encrypted)", + scheme = "https", + host = config.address, + port = address.getPort, + protocols = Set(HttpProtocol.HTTP_1_0, HttpProtocol.HTTP_1_1), + serverAttribute = serverHeader, + ssl = sslEngineProvider.map(_.sslContext()) + ) ) override val serverEndpoints: ServerEndpoints = ServerEndpoints(Http1Plain.toSeq ++ Http1Encrypted.toSeq) diff --git a/transport/server/play-netty-server/src/main/scala/play/core/server/netty/PlayRequestHandler.scala b/transport/server/play-netty-server/src/main/scala/play/core/server/netty/PlayRequestHandler.scala index 84e1cab6a14..4e5505aca25 100644 --- a/transport/server/play-netty-server/src/main/scala/play/core/server/netty/PlayRequestHandler.scala +++ b/transport/server/play-netty-server/src/main/scala/play/core/server/netty/PlayRequestHandler.scala @@ -166,16 +166,15 @@ private[play] class PlayRequestHandler( //handle bad websocket request case ws: WebSocket => logger.trace(s"Bad websocket request: $request") - val action = EssentialAction( - _ => - Accumulator.done( - Results - .Status(Status.UPGRADE_REQUIRED)("Upgrade to WebSocket required") - .withHeaders( - HeaderNames.UPGRADE -> "websocket", - HeaderNames.CONNECTION -> HeaderNames.UPGRADE - ) - ) + val action = EssentialAction(_ => + Accumulator.done( + Results + .Status(Status.UPGRADE_REQUIRED)("Upgrade to WebSocket required") + .withHeaders( + HeaderNames.UPGRADE -> "websocket", + HeaderNames.CONNECTION -> HeaderNames.UPGRADE + ) + ) ) handleAction(action, requestHeader, request, tryApp) diff --git a/transport/server/play-netty-server/src/main/scala/play/core/server/netty/WebSocketHandler.scala b/transport/server/play-netty-server/src/main/scala/play/core/server/netty/WebSocketHandler.scala index a5d979d6d45..e16ee901ee1 100644 --- a/transport/server/play-netty-server/src/main/scala/play/core/server/netty/WebSocketHandler.scala +++ b/transport/server/play-netty-server/src/main/scala/play/core/server/netty/WebSocketHandler.scala @@ -20,6 +20,7 @@ import play.core.server.common.WebSocketFlowHandler.MessageType import play.core.server.common.WebSocketFlowHandler.RawMessage private[server] object WebSocketHandler { + /** * Convert a flow of messages to a processor of frame events. * diff --git a/transport/server/play-server/src/main/scala/play/core/server/DevServerStart.scala b/transport/server/play-server/src/main/scala/play/core/server/DevServerStart.scala index b591fdde904..f6db8a077ac 100644 --- a/transport/server/play-server/src/main/scala/play/core/server/DevServerStart.scala +++ b/transport/server/play-server/src/main/scala/play/core/server/DevServerStart.scala @@ -29,6 +29,7 @@ import scala.util.Try * is reloaded whenever its source changes. */ object DevServerStart { + /** * Provides an HTTPS-only server for the dev environment. * diff --git a/transport/server/play-server/src/main/scala/play/core/server/ProdServerStart.scala b/transport/server/play-server/src/main/scala/play/core/server/ProdServerStart.scala index 06936e56d91..74b1d7cdf51 100644 --- a/transport/server/play-server/src/main/scala/play/core/server/ProdServerStart.scala +++ b/transport/server/play-server/src/main/scala/play/core/server/ProdServerStart.scala @@ -23,6 +23,7 @@ import play.api._ * immediately. */ object ProdServerStart { + /** * Start a prod mode server from the command line. */ @@ -143,11 +144,12 @@ object ProdServerStart { else { val pidFile = new File(pidFilePath).getAbsoluteFile val pid = process.pid.getOrElse(throw ServerStartException("Couldn't determine current process's pid")) - val out = try Files.newOutputStream(pidFile.toPath, StandardOpenOption.CREATE_NEW) - catch { - case _: FileAlreadyExistsException => - throw ServerStartException(s"This application is already running (or delete ${pidFile.getPath} file).") - } + val out = + try Files.newOutputStream(pidFile.toPath, StandardOpenOption.CREATE_NEW) + catch { + case _: FileAlreadyExistsException => + throw ServerStartException(s"This application is already running (or delete ${pidFile.getPath} file).") + } try out.write(pid.getBytes) finally out.close() Some(pidFile) diff --git a/transport/server/play-server/src/main/scala/play/core/server/SelfSigned.scala b/transport/server/play-server/src/main/scala/play/core/server/SelfSigned.scala index 544dbb6c327..e6f6570fa2e 100644 --- a/transport/server/play-server/src/main/scala/play/core/server/SelfSigned.scala +++ b/transport/server/play-server/src/main/scala/play/core/server/SelfSigned.scala @@ -18,6 +18,7 @@ import play.server.api.SSLEngineProvider /** Contains a statically initialized self-signed certificate. */ // public only for testing purposes @ApiMayChange object SelfSigned { + /** The SSLContext and TrustManager associated with the self-signed certificate. */ lazy val (sslContext, trustManager): (SSLContext, X509TrustManager) = { val keyStore: KeyStore = FakeKeyStore.generateKeyStore diff --git a/transport/server/play-server/src/main/scala/play/core/server/Server.scala b/transport/server/play-server/src/main/scala/play/core/server/Server.scala index a1b58402cbe..8789e81c832 100644 --- a/transport/server/play-server/src/main/scala/play/core/server/Server.scala +++ b/transport/server/play-server/src/main/scala/play/core/server/Server.scala @@ -87,6 +87,7 @@ trait Server extends ReloadableServer { * Utilities for creating a server that runs around a block of code. */ object Server { + /** * Try to get the handler for a request and return it as a `Right`. If we * can't get the handler for some reason then return a result immediately diff --git a/transport/server/play-server/src/main/scala/play/core/server/ServerEndpoint.scala b/transport/server/play-server/src/main/scala/play/core/server/ServerEndpoint.scala index 0f8b652cae8..bf9377b54c4 100644 --- a/transport/server/play-server/src/main/scala/play/core/server/ServerEndpoint.scala +++ b/transport/server/play-server/src/main/scala/play/core/server/ServerEndpoint.scala @@ -23,6 +23,7 @@ import akka.annotation.ApiMayChange serverAttribute: Option[String], ssl: Option[SSLContext] ) { + /** * Create a full URL out of a path. E.g. a path of `/foo` becomes `http://localhost:12345/foo` */ diff --git a/transport/server/play-server/src/main/scala/play/core/server/ServerProcess.scala b/transport/server/play-server/src/main/scala/play/core/server/ServerProcess.scala index 49df4869b40..3a5330a6b0d 100644 --- a/transport/server/play-server/src/main/scala/play/core/server/ServerProcess.scala +++ b/transport/server/play-server/src/main/scala/play/core/server/ServerProcess.scala @@ -14,6 +14,7 @@ import java.util.Properties * `System.getProperties()`, `System.exit()`, etc. */ trait ServerProcess { + /** The ClassLoader that should be used */ def classLoader: ClassLoader diff --git a/transport/server/play-server/src/main/scala/play/core/server/ServerProvider.scala b/transport/server/play-server/src/main/scala/play/core/server/ServerProvider.scala index db5b970d150..c0d5da2d568 100644 --- a/transport/server/play-server/src/main/scala/play/core/server/ServerProvider.scala +++ b/transport/server/play-server/src/main/scala/play/core/server/ServerProvider.scala @@ -31,6 +31,7 @@ trait ServerProvider { } object ServerProvider { + /** * The context for creating a server. Passed to the `createServer` method. * @@ -62,22 +63,24 @@ object ServerProvider { .getOptional[String](ClassNameConfigKey) .getOrElse(throw ServerStartException(s"No ServerProvider configured with key '$ClassNameConfigKey'")) - val clazz = try classLoader.loadClass(className) - catch { - case ex: ClassNotFoundException => - throw ServerStartException(s"Couldn't find ServerProvider class '$className'", cause = Some(ex)) - } + val clazz = + try classLoader.loadClass(className) + catch { + case ex: ClassNotFoundException => + throw ServerStartException(s"Couldn't find ServerProvider class '$className'", cause = Some(ex)) + } if (!classOf[ServerProvider].isAssignableFrom(clazz)) throw ServerStartException(s"Class ${clazz.getName} must implement ServerProvider interface") - val constructor = try clazz.getConstructor() - catch { - case ex: NoSuchMethodException => - throw ServerStartException( - s"ServerProvider class ${clazz.getName} must have a public default constructor", - cause = Some(ex) - ) - } + val constructor = + try clazz.getConstructor() + catch { + case ex: NoSuchMethodException => + throw ServerStartException( + s"ServerProvider class ${clazz.getName} must have a public default constructor", + cause = Some(ex) + ) + } constructor.newInstance().asInstanceOf[ServerProvider] } diff --git a/transport/server/play-server/src/main/scala/play/core/server/common/ForwardedHeaderHandler.scala b/transport/server/play-server/src/main/scala/play/core/server/common/ForwardedHeaderHandler.scala index bcc1d76e5db..cfc7bacb8b9 100644 --- a/transport/server/play-server/src/main/scala/play/core/server/common/ForwardedHeaderHandler.scala +++ b/transport/server/play-server/src/main/scala/play/core/server/common/ForwardedHeaderHandler.scala @@ -56,6 +56,7 @@ import play.api.mvc.request.RemoteConnection * */ private[server] class ForwardedHeaderHandler(configuration: ForwardedHeaderHandlerConfig) { + /** * Update connection information based on any forwarding information in the headers. * diff --git a/transport/server/play-server/src/main/scala/play/core/server/common/PathAndQueryParser.scala b/transport/server/play-server/src/main/scala/play/core/server/common/PathAndQueryParser.scala index bab7f99a646..68ea2f250c7 100644 --- a/transport/server/play-server/src/main/scala/play/core/server/common/PathAndQueryParser.scala +++ b/transport/server/play-server/src/main/scala/play/core/server/common/PathAndQueryParser.scala @@ -7,6 +7,7 @@ package play.core.server.common import java.net.URI private[server] object PathAndQueryParser { + /** * Parse URI String into path and query string parts. * The path part is validated using [[java.net.URI]]. diff --git a/transport/server/play-server/src/main/scala/play/core/server/common/ReloadCache.scala b/transport/server/play-server/src/main/scala/play/core/server/common/ReloadCache.scala index 44aa01cc4c9..bfed040daea 100644 --- a/transport/server/play-server/src/main/scala/play/core/server/common/ReloadCache.scala +++ b/transport/server/play-server/src/main/scala/play/core/server/common/ReloadCache.scala @@ -29,6 +29,7 @@ import scala.util.Try * `cachedValue` to get the cached value. */ private[play] abstract class ReloadCache[+T] { + /** * The count of how many times the cache has been reloaded. Due to the semantics of InlineCache this value * could be called up to once per thread per application change. diff --git a/transport/server/play-server/src/main/scala/play/core/server/common/ServerDebugInfo.scala b/transport/server/play-server/src/main/scala/play/core/server/common/ServerDebugInfo.scala index c248cff48af..5e7405f5a22 100644 --- a/transport/server/play-server/src/main/scala/play/core/server/common/ServerDebugInfo.scala +++ b/transport/server/play-server/src/main/scala/play/core/server/common/ServerDebugInfo.scala @@ -16,6 +16,7 @@ private[play] final case class ServerDebugInfo( ) private[play] object ServerDebugInfo { + /** The attribute used to attach debug info to requests. */ val Attr = TypedKey[ServerDebugInfo]("serverDebugInfo") diff --git a/transport/server/play-server/src/main/scala/play/core/server/common/WebSocketFlowHandler.scala b/transport/server/play-server/src/main/scala/play/core/server/common/WebSocketFlowHandler.scala index 76f8233a5f2..39a51aa681f 100644 --- a/transport/server/play-server/src/main/scala/play/core/server/common/WebSocketFlowHandler.scala +++ b/transport/server/play-server/src/main/scala/play/core/server/common/WebSocketFlowHandler.scala @@ -13,6 +13,7 @@ import play.api.Logger import play.api.http.websocket._ object WebSocketFlowHandler { + /** * Implements the WebSocket protocol, including correctly handling the closing of the WebSocket, as well as * other control frames like ping/pong. diff --git a/web/play-filters-helpers/src/main/scala/play/filters/cors/AbstractCORSPolicy.scala b/web/play-filters-helpers/src/main/scala/play/filters/cors/AbstractCORSPolicy.scala index 22a4f70ac54..28d2fe639bd 100644 --- a/web/play-filters-helpers/src/main/scala/play/filters/cors/AbstractCORSPolicy.scala +++ b/web/play-filters-helpers/src/main/scala/play/filters/cors/AbstractCORSPolicy.scala @@ -121,15 +121,16 @@ private[cors] trait AbstractCORSPolicy { .addAttr(CORSFilter.Attrs.Origin, origin) // We must recover any errors so that we can add the headers to them to allow clients to see the result - val result = try { - next(taggedRequest).recoverWith { + val result = + try { + next(taggedRequest).recoverWith { + case e: Throwable => + errorHandler.onServerError(taggedRequest, e) + } + } catch { case e: Throwable => - errorHandler.onServerError(taggedRequest, e) + Accumulator.done(errorHandler.onServerError(taggedRequest, e)) } - } catch { - case e: Throwable => - Accumulator.done(errorHandler.onServerError(taggedRequest, e)) - } result.map(addCorsHeaders(_, origin)) } } diff --git a/web/play-filters-helpers/src/main/scala/play/filters/cors/CORSActionBuilder.scala b/web/play-filters-helpers/src/main/scala/play/filters/cors/CORSActionBuilder.scala index b60c4e52b6f..f2cbb41df7f 100644 --- a/web/play-filters-helpers/src/main/scala/play/filters/cors/CORSActionBuilder.scala +++ b/web/play-filters-helpers/src/main/scala/play/filters/cors/CORSActionBuilder.scala @@ -73,6 +73,7 @@ trait CORSActionBuilder extends ActionBuilder[Request, AnyContent] with Abstract * @see [[http://www.w3.org/TR/cors/ CORS specification]] */ object CORSActionBuilder { + /** * Construct an action builder that uses a subtree of the application configuration. * diff --git a/web/play-filters-helpers/src/main/scala/play/filters/cors/CORSConfig.scala b/web/play-filters-helpers/src/main/scala/play/filters/cors/CORSConfig.scala index 1924985e97e..a69b35e2c6a 100644 --- a/web/play-filters-helpers/src/main/scala/play/filters/cors/CORSConfig.scala +++ b/web/play-filters-helpers/src/main/scala/play/filters/cors/CORSConfig.scala @@ -82,6 +82,7 @@ case class CORSConfig( * Helpers to build CORS policy configurations */ object CORSConfig { + /** * Origins allowed by the CORS filter */ diff --git a/web/play-filters-helpers/src/main/scala/play/filters/csp/CSPActionBuilder.scala b/web/play-filters-helpers/src/main/scala/play/filters/csp/CSPActionBuilder.scala index 8d5fbc63b60..0db66f42644 100644 --- a/web/play-filters-helpers/src/main/scala/play/filters/csp/CSPActionBuilder.scala +++ b/web/play-filters-helpers/src/main/scala/play/filters/csp/CSPActionBuilder.scala @@ -60,6 +60,7 @@ trait CSPActionBuilder extends ActionBuilder[Request, AnyContent] { * Useful in compile time dependency injection. */ object CSPActionBuilder { + /** * Creates a new CSPActionBuilder using a Configuration and bodyParsers instance. */ diff --git a/web/play-filters-helpers/src/main/scala/play/filters/csp/CSPConfig.scala b/web/play-filters-helpers/src/main/scala/play/filters/csp/CSPConfig.scala index 4d1a1d3add5..cded34e1b55 100644 --- a/web/play-filters-helpers/src/main/scala/play/filters/csp/CSPConfig.scala +++ b/web/play-filters-helpers/src/main/scala/play/filters/csp/CSPConfig.scala @@ -60,6 +60,7 @@ case class CSPConfig( * from configuration. */ object CSPConfig { + /** * Creates CSPConfig from a raw Configuration object, using "play.filters.csp". * @@ -145,6 +146,7 @@ case class CSPNonceConfig( pattern: String = CPSNonceConfig.DEFAULT_CSP_NONCE_PATTERN, header: Boolean = true ) { + /** Java constructor */ def this() = this(true) diff --git a/web/play-filters-helpers/src/main/scala/play/filters/csp/CSPProcessor.scala b/web/play-filters-helpers/src/main/scala/play/filters/csp/CSPProcessor.scala index 7518e747cf9..66350f959e6 100644 --- a/web/play-filters-helpers/src/main/scala/play/filters/csp/CSPProcessor.scala +++ b/web/play-filters-helpers/src/main/scala/play/filters/csp/CSPProcessor.scala @@ -17,6 +17,7 @@ import play.api.mvc.request.RequestAttrKey * This trait processes a request header for CSP related logic. */ trait CSPProcessor { + /** * Inspects the request header, and returns a CSPResult if the * request should be subject to CSP processing. @@ -74,8 +75,8 @@ class DefaultCSPProcessor @Inject() (config: CSPConfig) extends CSPProcessor { } .getOrElse(cspLine) - hashPatterns.foldLeft(cspLineWithNonce)( - (line, pair) => pair._1.matcher(line).replaceAll(Matcher.quoteReplacement(s"'${pair._2}'")) + hashPatterns.foldLeft(cspLineWithNonce)((line, pair) => + pair._1.matcher(line).replaceAll(Matcher.quoteReplacement(s"'${pair._2}'")) ) } diff --git a/web/play-filters-helpers/src/main/scala/play/filters/csrf/CSRFActions.scala b/web/play-filters-helpers/src/main/scala/play/filters/csrf/CSRFActions.scala index 9a4c2830415..cbae7a6af7e 100644 --- a/web/play-filters-helpers/src/main/scala/play/filters/csrf/CSRFActions.scala +++ b/web/play-filters-helpers/src/main/scala/play/filters/csrf/CSRFActions.scala @@ -390,6 +390,7 @@ class CSRFActionHelper( tokenSigner: CSRFTokenSigner, tokenProvider: TokenProvider ) { + /** Set of Cache-Control header directives that will explicitly prevent response caching in shared caches (e.g. proxies). */ private val NoCacheDirectives = Set("no-cache", "no-store", "private") diff --git a/web/play-filters-helpers/src/main/scala/play/filters/csrf/csrf.scala b/web/play-filters-helpers/src/main/scala/play/filters/csrf/csrf.scala index 8be297d430b..4521870ade8 100644 --- a/web/play-filters-helpers/src/main/scala/play/filters/csrf/csrf.scala +++ b/web/play-filters-helpers/src/main/scala/play/filters/csrf/csrf.scala @@ -235,6 +235,7 @@ object CSRF { * This abstraction allows the use of randomised tokens. */ trait TokenProvider { + /** Generate a token */ def generateToken: String @@ -272,6 +273,7 @@ object CSRF { * This trait handles the CSRF error. */ trait ErrorHandler { + /** Handle a result */ def handle(req: RequestHeader, msg: String): Future[Result] } diff --git a/web/play-filters-helpers/src/main/scala/play/filters/hosts/AllowedHostsFilter.scala b/web/play-filters-helpers/src/main/scala/play/filters/hosts/AllowedHostsFilter.scala index 8841aa1a854..a99f6adf424 100644 --- a/web/play-filters-helpers/src/main/scala/play/filters/hosts/AllowedHostsFilter.scala +++ b/web/play-filters-helpers/src/main/scala/play/filters/hosts/AllowedHostsFilter.scala @@ -94,6 +94,7 @@ case class AllowedHostsConfig(allowed: Seq[String], shouldProtect: RequestHeader } object AllowedHostsConfig { + /** * Parses out the AllowedHostsConfig from play.api.Configuration (usually this means application.conf). */ diff --git a/web/play-filters-helpers/src/test/scala/play/filters/csrf/CSRFCommonSpecs.scala b/web/play-filters-helpers/src/test/scala/play/filters/csrf/CSRFCommonSpecs.scala index f338a81c3a6..b64c0ca0d63 100644 --- a/web/play-filters-helpers/src/test/scala/play/filters/csrf/CSRFCommonSpecs.scala +++ b/web/play-filters-helpers/src/test/scala/play/filters/csrf/CSRFCommonSpecs.scala @@ -72,36 +72,32 @@ trait CSRFCommonSpecs extends Specification with PlaySpecification { // accept/reject tokens "accept requests with token in query string" in { lazy val token = generate - csrfCheckRequest( - req => - addToken(req.withQueryStringParameters(TokenName -> token), token) - .post(Map("foo" -> "bar")) + csrfCheckRequest(req => + addToken(req.withQueryStringParameters(TokenName -> token), token) + .post(Map("foo" -> "bar")) )(_.status must_== OK) } "accept requests with token in form body" in { lazy val token = generate - csrfCheckRequest( - req => - addToken(req, token) - .post(Map("foo" -> "bar", TokenName -> token)) + csrfCheckRequest(req => + addToken(req, token) + .post(Map("foo" -> "bar", TokenName -> token)) )(_.status must_== OK) } "accept requests with a session token and token in multipart body" in { lazy val token = generate - csrfCheckRequest( - req => - addToken(req, token) - .addHttpHeaders("Content-Type" -> s"multipart/form-data; boundary=$Boundary") - .post(multiPartFormDataBody(TokenName, token)) + csrfCheckRequest(req => + addToken(req, token) + .addHttpHeaders("Content-Type" -> s"multipart/form-data; boundary=$Boundary") + .post(multiPartFormDataBody(TokenName, token)) )(_.status must_== OK) } "accept requests with token in header" in { lazy val token = generate - csrfCheckRequest( - req => - addToken(req, token) - .addHttpHeaders(HeaderName -> token) - .post(Map("foo" -> "bar")) + csrfCheckRequest(req => + addToken(req, token) + .addHttpHeaders(HeaderName -> token) + .post(Map("foo" -> "bar")) )(_.status must_== OK) } "reject requests with nocheck header" in { @@ -119,17 +115,15 @@ trait CSRFCommonSpecs extends Specification with PlaySpecification { )(_.status must_== errorStatusCode) } "reject requests with different token in body" in { - csrfCheckRequest( - req => - addToken(req, generate) - .post(Map("foo" -> "bar", TokenName -> generate)) + csrfCheckRequest(req => + addToken(req, generate) + .post(Map("foo" -> "bar", TokenName -> generate)) )(_.status must_== errorStatusCode) } "reject requests with token in session but none elsewhere" in { - csrfCheckRequest( - req => - addToken(req, generate) - .post(Map("foo" -> "bar")) + csrfCheckRequest(req => + addToken(req, generate) + .post(Map("foo" -> "bar")) )(_.status must_== errorStatusCode) } "reject requests with token in body but not in session" in { diff --git a/web/play-filters-helpers/src/test/scala/play/filters/gzip/GzipFilterSpec.scala b/web/play-filters-helpers/src/test/scala/play/filters/gzip/GzipFilterSpec.scala index f449895dbe2..51002c00b53 100644 --- a/web/play-filters-helpers/src/test/scala/play/filters/gzip/GzipFilterSpec.scala +++ b/web/play-filters-helpers/src/test/scala/play/filters/gzip/GzipFilterSpec.scala @@ -328,8 +328,8 @@ class GzipFilterSpec extends PlaySpecification with DataTables { } "a chunked body" should { - val chunkedBody = Source.fromIterator( - () => Seq[HttpChunk](HttpChunk.Chunk(ByteString("First chunk")), HttpChunk.LastChunk(FakeHeaders())).iterator + val chunkedBody = Source.fromIterator(() => + Seq[HttpChunk](HttpChunk.Chunk(ByteString("First chunk")), HttpChunk.LastChunk(FakeHeaders())).iterator ) val entity = HttpEntity.Chunked(chunkedBody, Some("text/plain")) @@ -384,14 +384,13 @@ class GzipFilterSpec extends PlaySpecification with DataTables { ) { implicit app => val result = makeGzipRequest(app) checkGzipped(result) - header(VARY, result) must beSome.which( - header => - header - .split(",") - .count( - _.toLowerCase(java.util.Locale.ENGLISH) == ACCEPT_ENCODING - .toLowerCase(java.util.Locale.ENGLISH) - ) == 1 + header(VARY, result) must beSome.which(header => + header + .split(",") + .count( + _.toLowerCase(java.util.Locale.ENGLISH) == ACCEPT_ENCODING + .toLowerCase(java.util.Locale.ENGLISH) + ) == 1 ) } } diff --git a/web/play-java-forms/src/main/scala/play/core/PlayFormsMagicForJava.scala b/web/play-java-forms/src/main/scala/play/core/PlayFormsMagicForJava.scala index 7e048b4dcea..9c8c9e46336 100644 --- a/web/play-java-forms/src/main/scala/play/core/PlayFormsMagicForJava.scala +++ b/web/play-java-forms/src/main/scala/play/core/PlayFormsMagicForJava.scala @@ -18,20 +18,18 @@ object PlayFormsMagicForJava { null, jField.name.orElse(null), Option(jField.constraints) - .map( - c => - c.asScala.toSeq.map { jT => - jT._1 -> jT._2.asScala.toSeq - } + .map(c => + c.asScala.toSeq.map { jT => + jT._1 -> jT._2.asScala.toSeq + } ) .getOrElse(Nil), Option(jField.format).map(f => f._1 -> f._2.asScala.toSeq), Option(jField.errors) - .map( - e => - e.asScala.toSeq.map { jE => - play.api.data.FormError(jE.key, jE.messages.asScala.toSeq, jE.arguments.asScala.toSeq) - } + .map(e => + e.asScala.toSeq.map { jE => + play.api.data.FormError(jE.key, jE.messages.asScala.toSeq, jE.arguments.asScala.toSeq) + } ) .getOrElse(Nil), OptionConverters.toScala(jField.value) diff --git a/web/play-joda-forms/src/main/scala/play/api/data/format/JodaFormats.scala b/web/play-joda-forms/src/main/scala/play/api/data/format/JodaFormats.scala index 60f102dccfd..94e72ed39a4 100644 --- a/web/play-joda-forms/src/main/scala/play/api/data/format/JodaFormats.scala +++ b/web/play-joda-forms/src/main/scala/play/api/data/format/JodaFormats.scala @@ -7,6 +7,7 @@ package play.api.data.format import play.api.data._ object JodaFormats { + /** * Helper for formatters binders * @param parse Function parsing a String value into a T value, throwing an exception in case of failure diff --git a/web/play-openid/src/main/scala/play/api/libs/openid/OpenIdClient.scala b/web/play-openid/src/main/scala/play/api/libs/openid/OpenIdClient.scala index 56a0fda6dca..cf100d94eab 100644 --- a/web/play-openid/src/main/scala/play/api/libs/openid/OpenIdClient.scala +++ b/web/play-openid/src/main/scala/play/api/libs/openid/OpenIdClient.scala @@ -72,6 +72,7 @@ object UserInfo { } trait OpenIdClient { + /** * Retrieve the URL where the user should be redirected to start the OpenID authentication process */ @@ -98,6 +99,7 @@ trait OpenIdClient { class WsOpenIdClient @Inject() (ws: WSClient, discovery: Discovery)(implicit ec: ExecutionContext) extends OpenIdClient with WSBodyWritables { + /** * Retrieve the URL where the user should be redirected to start the OpenID authentication process */ @@ -198,6 +200,7 @@ class WsOpenIdClient @Inject() (ws: WSClient, discovery: Discovery)(implicit ec: } trait Discovery { + /** * Resolve the OpenID server from the user's OpenID */