Lagom: Prevent deprecation warnings in documentation

[ignasi35]

There's few improvements to be done in Persistent Entity (scaladsl v1.3):

Example code in tests uses scalactic's ConversionCheckedTripleEquals which is deprecated in favour of TypeCheckedTripleEquals.

[TimMoore]

The code in question is in PostSpec.

You can see the deprecation warnings by running:

cd docs
sbt 'set scalacOptions += "-deprecation"' test:clean test:compile

See also #1282.

[TimMoore]

Let's also make the documentation build fail on warnings once these are fixed.

[erip]

Is this done?

[ignasi35]

Hi @erip I think there's some bits still pending. Looking at #1421 I think the ConversionChekckTripleEquals issue was solved but I'm not sure about the update of PostSpec @timmoore and I mention above.

I don't think we have a way to fail the build in case of warnings but, in any case, it should be done in a separate PR.

[marcospereira]

Hi @erip I think there's some bits still pending. Looking at #1421 I think the ConversionChekckTripleEquals issue was solved but I'm not sure about the update of PostSpec @timmoore and I mention above.

I think the problem @TimMoore was describing was the use of ConversionCheckedTripleEquals in PostSpec. If so, this is solved. What is not solved is that code samples are still referencing some Lagom APIs that are deprecated.

Anyway, the best option here is to compile the docs and see what shows up. :-)

If not relevant shows up, then I think we can fix it. Or we can consider that removing deprecated APIs (#1432) should also force the removal of sample codes using them.

WDYT?

[marcospereira]

Hum, looks like we can close this since #1419 removed the last bit of deprecated APIs used in docs.

Can someone else confirm this?

[erip]

@marcospereira Depending on how we interpret "in documentation", there may or may not be warnings still. Example:

lagom/docs/build.sbt:136: warning: method apply in object SubProcess is deprecated: Construct SubProcess with a ForkOptions argument.
      runPolicy = Tests.SubProcess(javaOptions))

Other offendors:

warn] lagom/service/scaladsl/server/src/main/scala/com/lightbend/lagom/scaladsl/server/LagomApplicationLoader.scala:47: method describeServices in class LagomApplicationLoader is deprecated (since 1.3.3): Binding multiple locatable ServiceDescriptors per Lagom service is unsupported. Override LagomApplicationLoader.describeService() instead
[warn]     describeServices match {
[warn]     ^
[warn] lagom/service/scaladsl/server/src/main/scala/com/lightbend/lagom/scaladsl/server/LagomApplicationLoader.scala:143: method describeServices in class LagomApplicationLoader is deprecated (since 1.3.3): Binding multiple locatable ServiceDescriptors per Lagom service is unsupported. Override LagomApplicationLoader.describeService() instead
[warn]     describeServices.map { descriptor =>
[warn]     ^

[TimMoore]

I just did a sneaky and updated the title to "Prevent deprecation warnings in documentation", expanding the scope of the issue 😉. This actually just brings it in line with my comment above:

Let's also make the documentation build fail on warnings once these are fixed.

The point is that we don't want to demonstrate deprecated code in our documentation examples, now or in the future. Both Scala and Java compilers support options to fail on warnings, and we should set those in the documentation build.

@erip fixing warnings in docs/build.sbt itself (or anywhere else in the Lagom code base) is always appreciated, but not really the point of this issue.

In the case of LagomApplicationLoader, this is where deprecated code is used to maintain backwards compatibility, so I think it's best to leave it alone until the deprecated API is removed in 2.0.