guardrail-dev / guardrail-dev/guardrail

guardrail should not emit code that uses `$` symbol

Open
#2,101 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
Scala
Stars
541
Forks
138
PR merge metrics
No merged PRs in 30d

Description

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 `$`.

```scala
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.

https://github.com/guardrail-dev/guardrail/blob/cd6955bcaeaa5035c490055b0b392b5fee62d436/modules/scala-support/src/main/scala/dev/guardrail/generators/scala/ScalaGenerator.scala#L265

https://github.com/guardrail-dev/guardrail/blob/cd6955bcaeaa5035c490055b0b392b5fee62d436/modules/scala-support/src/main/scala/dev/guardrail/generators/scala/ScalaGenerator.scala#L358

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 https://github.com/guardrail-dev/guardrail/pull/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.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.