guardrail should not emit code that uses `$` symbol

[i10416]

Hi, maintainers.

I came across a situation where scaladoc fails to generate doc because of identifier name guardrail generates.

guardrail emits the code similar to the following example, which prevents scaladoc from generating doc.
This results from the identifier containing $.

object definition$ {
   val codec = // ...
   // ....
}

package object definition {
  implicit val codec = definition$.codec
  // ...
}

guardrail should not emit code that uses $ symbol for identifier, especially for object declaration.

guardrail/modules/scala-support/src/main/scala/dev/guardrail/generators/scala/ScalaGenerator.scala

Line 265 in cd6955b

s"&$${ev.addArg(key, value)}"

guardrail/modules/scala-support/src/main/scala/dev/guardrail/generators/scala/ScalaGenerator.scala

Line 358 in cd6955b

companion = Term.Name(s"${dtoRestNel.last}$$")

Scala specification states that $ is not allowed for identifiers.

The ‘$’ character is reserved for compiler-synthesized identifiers. User programs should not define identifiers which contain ‘$’ characters.

https://www.scala-lang.org/files/archive/spec/2.11/01-lexical-syntax.html

In Scala 3, identifier with $ confuses the compiler while unpickling and scaladoc fails to generate doc.

Here is the repro. https://github.com/i10416/repro-scaladoc-error-on-dollar-symbol

The $ suffix naming convention was introduced in this PR #135

I think we should replace $ with another one because the identifier containing $ will be deprecated and result in compile error in the future.

What do you think of replacing $ with another one such as _?

BTW, this will introduce breaking change.
In order to avoid sudden breakage in downstream ecosystem, we could inform downstream developers who directly uses definition$ by applying @deprecated annotation on object definition$ and then we can replace $ with another one.