Formatter relocates docs when function is commented out

[digitalcora]

Example:

/// Does something.
pub fn func1() {
  todo
}

/// Does something else.
pub fn func2() {
  todo
}

I'm working on func1, but in the middle of that, realize I want to make changes somewhere else first. The code in func1 is (temporarily) invalid syntax and will make the formatter throw an error, so I comment it out:

/// Does something.
//pub fn func1() {
//  some half-baked code in here
//}

/// Does something else.
pub fn func2() {
  todo
}

Then, while making those other changes somewhere else, I run the formatter:

//pub fn func1() {
//  some half-baked code in here
//}

/// Does something.
/// Does something else.
pub fn func2() {
  todo
}

My intended doc comment for func1 has been "merged" into the doc for func2. This also happens if func2 has no doc; the func1 doc is relocated to just above func2.

After seeing this I can understand why it happens, but it was still pretty unexpected, and could introduce mistakes into published docs if you don't notice it happening.

My initial suggestion would be that a "floating" doc comment like this should be treated as a normal comment when parsing, and that maybe gleam docs should output a warning about it ("function doc ignored: not connected to a function"). This seems like it might be a bit complicated to implement, though...

There is also the workaround of only commenting out the function body and not the whole definition, which will cause the formatter to insert a todo but otherwise not mess with it. I'd be fine if the solution is "just remember to do it that way"; this is not something I expect to come up very often.

[lpil]

Hello! It would be good to fix this for sure, though it will be a bit fiddly.