roc
roc copied to clipboard
roc-lang
Doc comments with code snippets don't re-format the same way
To reproduce, edit examples/hello-world/Hello.roc to include this doc comment:
app "hello-world"
packages { pf: "platform" }
imports []
provides [ main ] to pf
## Greets the user
##
## Blah
main = "Hello, World!\n"
Then run cargo run format examples/hello-world/Hello.roc
Expected: It formats the file successfully
Actual: It panics with Formatting bug; formatting is not stable. Reformatting the formatted file changed it again.
Specifically what happens is that re-formatting the already-formatted code changes the indentation of Blah, which is interpreted (correctly) as a code snippet.
What should happen instead is that the first time this gets formatted, the indentation for Blah is set, and then running the formatter on it a second time should not change anything. (Running the formatter a second time on code that has already been formatted should never change anything, which is why we detect this case and explicitly panic if it happens!)
the first time this gets formatted, the indentation for Blah is set,
Do you mean that any code that is indented by 1 + 4 spaces inside doc comments should be formated as if is was code (expect, with a prefix of ## ?)
Should the "misaligned" non-doc comments be aligned ? Or should they preserve their formating ?
So, assuming: Original:
## Greet the user /* 1 + 0 spaces */
## Misaligned comment /* 1 + 1 space */
## CodeIndentifier = /* 1 + 4 */
## 42 /* 1 + 4 + 2 */
## MisalignedCodeIdentifier /* 1 + 4 + 1 */
Do we want the stable indentation to be this ?
## Greet the user /* 1 + 0 spaces */
## Misaligned comment /* 1 + 1 space */
## CodeIndentifier = /* 1 + 4 spaces */
## 42 /* 1 + 4 + 4 spaces */
## MisalignedCodeIdentifier /* 1 + 4 spaces */
This is a hackish way to handle it : https://github.com/rtfeldman/roc/commit/0f24de6b6077a2fbfe4c760c50648473844bf75a
It seems like really formatting anything inside code blocks would involve recursively calling the formater inside spaces.rs, and that would involve a circular dependency... so maybe not worth it ?
Do you mean that any code that is indented by 1 + 4 spaces inside doc comments should be formatted as if is was code (expect, with a prefix of
##?)
Yes, exactly!
Should the "misaligned" non-doc comments be aligned ? Or should they preserve their formating ?
I think we should assume that every line beginning with ## followed by 5+ spaces is code, and we should format it rather than preserving its formatting. 👍
Indeed this is recursive...it would be silly, but theoretically you could have a doc comment with a code snippet that contains another doc comment with another code snippet, and they should all be formatted. 😄
However, I don't think we necessarily need to make that work right away! Fixing this issue would be a lovely step forward, and we could always improve support for doc comments inside doc comments in the future!
The code's latest version doesn't have this problem. I added that comment to examples/helloWorld.roc and ran cargo run format examples/helloWorld.roc twice. The first time, it removed the file's extra line at the end, and the second time, it exited successfully.
Running roc format now confirms the findings of @cjduncana. Is this enough to close this issue, @Anton-4?
