Render deprecation hints #599

kubukoz · 2022-11-12T03:56:33Z

Made a separate commit for the actual implementation so that you can see how it affects the deprecated shapes:

files in modules/example of this commit

I think this doesn't have to go into 0.17 as it wouldn't make breaking changes.

Edit: about the above, I think this might be source breaking in a way (people might have fatal warnings on). Let's stick it into 0.17.

Solves the deprecation part of #256

build.sbt

modules/codegen/src/smithy4s/codegen/IR.scala

kubukoz · 2022-11-12T03:58:30Z

modules/codegen/src/smithy4s/codegen/Renderer.scala

-    case _ => Lines.empty
+  }
+
+  private def deprecationAnnotation(hints: List[Hint]): Line = {


the implementation feels a bit dirty, suggestions welcome

the only thing I'd change here is have an extra map, before the that's already there where I call renderStringLiteral before building the line to avoid ${renderStringLiteral(msg)}

tbh I actually like that renderStringLiteral is being interpolated (as long as it doesn't break the line)

kubukoz · 2022-11-12T03:59:23Z

modules/codegen/src/smithy4s/codegen/Renderer.scala

@@ -166,6 +185,7 @@ private[codegen] class Renderer(compilationUnit: CompilationUnit) { self =>
      val name = s.name
      val nameGen = NameRef(s"${name}Gen")
      lines(
+        deprecationAnnotation(s.hints),


Thought it would make sense to deprecate just the service trait and type alias, but we could deprecate the companion object / val alias as well. I don't have a strong opinion on this.

modules/codegen/src/smithy4s/codegen/Renderer.scala

kubukoz · 2022-11-12T04:08:37Z

modules/codegen/src/smithy4s/codegen/SmithyToIR.scala

@@ -273,7 +273,8 @@ private[codegen] class SmithyToIR(model: Model, namespace: String) {
                    value.getName().asScala,
                    value.getValue,
                    index
-                  )
+                  ),
+                  hints = Nil


AFAIK 1.x enums don't allow hints on values.

That is correct

modules/codegen/src/smithy4s/codegen/SmithyToIR.scala

kubukoz · 2022-11-12T04:09:39Z

modules/codegen/src/smithy4s/codegen/SmithyToIR.scala

        val values = shape
          .getEnumValues()
          .asScala
          .map { case (name, value) =>
-            EnumValue(name, value, name)
+            val member = shape.getMember(name).get()


feels a bit odd to do the lookup like this, but it's not that much repetition and it should be safe at all times.

modules/codegen/src/smithy4s/codegen/SmithyToIR.scala

kubukoz · 2022-11-12T04:11:21Z

project/Smithy4sBuildPlugin.scala

+    // Ignores warnings in code using the deprecated Enum trait.
+    scalacOptions += "-Wconf:msg=object Enum in package api is deprecated:silent"


FYI here's what Enum now generates as:

@deprecated(message = "The enum trait is replaced by the enum shape in Smithy 2.0", since = "2.0") object Enum extends Newtype[List[EnumDefinition]] { val id: ShapeId = ShapeId("smithy.api", "enum") val hints : Hints = Hints( smithy.api.Documentation("Constrains the acceptable values of a string to a fixed set\nof constant values."), smithy.api.Trait(selector = Some("string :not(enum)"), structurallyExclusive = None, conflicts = None, breakingChanges = Some(List(smithy.api.TraitDiffRule(change = smithy.api.TraitChangeType.PRESENCE.widen, severity = smithy.api.TraitChangeSeverity.ERROR.widen, path = None, message = None)))), smithy.api.Deprecated(message = Some("The enum trait is replaced by the enum shape in Smithy 2.0"), since = Some("2.0")), ) val underlyingSchema : Schema[List[EnumDefinition]] = list(EnumDefinition.schema).withId(id).addHints(hints).validated(smithy.api.Length(min = Some(1), max = None)) implicit val schema : Schema[Enum] = recursive(bijection(underlyingSchema, asBijection)) }

kubukoz · 2022-11-12T14:44:47Z

I'll get back to this after the weekend, most likely

kubukoz · 2022-11-17T23:13:16Z

@Baccata I think this is ready to go from my side

modules/codegen/src/smithy4s/codegen/Renderer.scala

daddykotex · 2022-11-18T01:14:15Z

modules/codegen/src/smithy4s/codegen/Renderer.scala

@@ -988,4 +1023,15 @@ private[codegen] class Renderer(compilationUnit: CompilationUnit) { self =>
      case _ => _ => line"null"
    }

+  private def renderStringLiteral(raw: String): Line = {
+    import scala.reflect.runtime.universe._


what is the import used for?

Literal and Constant

daddykotex · 2022-11-18T01:16:24Z

modules/example/src/smithy4s/example/DeprecatedStructure.scala

+import smithy4s.schema.Schema.struct
+import smithy4s.ShapeTag
+
+@deprecated(message = "A compelling reason", since = "0.0.1")


daddykotex

great job, it's more work that I had anticipated
kudos on the work on dynamic, this PR serves as a great reference if for changes that would need to apply there as well

modules/example/src/smithy4s/example/Letters.scala

modules/codegen/src/smithy4s/codegen/SmithyToIR.scala

Baccata · 2022-11-19T23:09:49Z

modules/codegen/src/smithy4s/codegen/SmithyToIR.scala

@@ -742,6 +740,8 @@ private[codegen] class SmithyToIR(model: Model, namespace: String) {
        // traits from the synthetic namespace, e.g. smithy.synthetic.enum
        // don't have shapes in the model - so we can't generate hints for them.
        .filterNot(_.toShapeId().getNamespace() == "smithy.synthetic")
+        // enumValue can be derived from enum schemas anyway, so we're removing it from hints
+        .filterNot(_.toShapeId().toString() == "smithy.api#enumValue")


thy shall not use .toString when there is an alternative (in this case, ShapeId.fromParts("smithy.api", "enumValue") or probably even EnumValueTrait.ID or something

now you're just nitpicking :P

Nah, just .toString trauma 😄

:heavy-nodding:

kubukoz commented Nov 12, 2022

View reviewed changes

kubukoz added 2 commits November 12, 2022 05:15

Add sample specs to showcase rendering

918154c

WIP: render deprecation hints

d5b5a81

kubukoz force-pushed the render-deprecation branch from 39686e1 to d5b5a81 Compare November 12, 2022 04:16

kubukoz added 2 commits November 12, 2022 05:18

Ignore warnings on the type alias as well

b3507b8

Fix compile

c683bb2

kubukoz mentioned this pull request Nov 12, 2022

Hints on collection members aren't generated #600

Closed

kubukoz mentioned this pull request Nov 12, 2022

Adding -source:future causes compilation errors due to deprecated wildcard syntax #496

Closed

kubukoz added 5 commits November 17, 2022 12:23

Merge branch 'series/0.17' into render-deprecation

61e2426

Add comment

fe25197

Render enum value hints + add appendIf

f833189

renderTypeAlias -> renderNewtype

0bc490d

Document synthetic namespace

f274458

kubukoz mentioned this pull request Nov 17, 2022

Support collection member hints in codegen #609

Closed

Add enum value hints in dynamic model compiler

e18ba3a

kubukoz marked this pull request as ready for review November 17, 2022 23:11

daddykotex reviewed Nov 18, 2022

View reviewed changes

modules/codegen/src/smithy4s/codegen/Renderer.scala Outdated Show resolved Hide resolved

daddykotex reviewed Nov 18, 2022

View reviewed changes

daddykotex approved these changes Nov 18, 2022

View reviewed changes

Extract lines

b5a314c

Baccata reviewed Nov 19, 2022

View reviewed changes

modules/example/src/smithy4s/example/Letters.scala Outdated Show resolved Hide resolved

Baccata reviewed Nov 19, 2022

View reviewed changes

modules/codegen/src/smithy4s/codegen/SmithyToIR.scala Outdated Show resolved Hide resolved

Remove EnumValue from generated/compiled hints

4cb289b

Baccata reviewed Nov 19, 2022

View reviewed changes

Avoid toString

0072756

Baccata approved these changes Nov 19, 2022

View reviewed changes

kubukoz merged commit b1246cc into series/0.17 Nov 20, 2022

kubukoz deleted the render-deprecation branch November 20, 2022 00:21

Baccata added this to the 0.17.0 milestone Nov 23, 2022

zetashift mentioned this pull request Jan 13, 2023

Generate Scaladoc #256

Closed

i10416 mentioned this pull request May 29, 2023

@deprecated w/o argument is deprecated #948

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Render deprecation hints #599

Render deprecation hints #599

kubukoz commented Nov 12, 2022 •

edited

kubukoz Nov 12, 2022

daddykotex Nov 18, 2022

kubukoz Nov 18, 2022

kubukoz Nov 12, 2022

kubukoz Nov 12, 2022

Baccata Nov 12, 2022

kubukoz Nov 12, 2022

kubukoz Nov 12, 2022

kubukoz commented Nov 12, 2022

kubukoz commented Nov 17, 2022

daddykotex Nov 18, 2022

kubukoz Nov 18, 2022

daddykotex Nov 18, 2022

daddykotex left a comment

Baccata Nov 19, 2022

kubukoz Nov 19, 2022

Baccata Nov 19, 2022

kubukoz Nov 19, 2022

		// Ignores warnings in code using the deprecated Enum trait.
		scalacOptions += "-Wconf:msg=object Enum in package api is deprecated:silent"

Render deprecation hints #599

Render deprecation hints #599

Conversation

kubukoz commented Nov 12, 2022 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

kubukoz commented Nov 12, 2022

kubukoz commented Nov 17, 2022

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

daddykotex left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

kubukoz commented Nov 12, 2022 •

edited