feat(fmt): improve newline insertion when comments are in between leaf spans

[eightfilms]

Closes #4185

Description

The solution we adopted as a start would have us take the space between leaf spans, except a problem was that a doc comment would be a leaf span but a regular comment would not be a leaf span. Usually this would not be an issue, but in certain cases where we perhaps want to comment code out temporarily to test changes, the formatter would move comments around unintentionally.

For example, a doc comment followed by a commented out function (as shown in the issue) would cause the commented out function to move away from the doc comment:

contract;

abi MyContract {
    fn test_function() -> bool;
}

impl MyContract for Contract {
    /// This is documentation for a commented out function <-- a newline is inserted after this comment
    // fn commented_out_function() {
    //}

    fn test_function() -> bool {
        true
    }
}

Situations like these could ruin developer experience.

The main problem is that the entire whitespace gap between 2 leaf spans could have multiple comments with multiple newline sequences, and all these would be squished to the end of the first leaf span when inserting the newlines.

The fix is to take 'snippets' while we're scanning for newline sequences to insert and try to detect comments within these snippets. We then split insertion of newline sequences into two phases: one before the first comment (which is described above, which caused the issue above), one after the last comment.

Checklist

• I have linked to any relevant issues.
• I have commented my code, particularly in hard-to-understand areas.
• I have updated the documentation where relevant (API docs, the reference, and the Sway book).
• I have added tests that prove my fix is effective or that my feature works.
• I have added (or requested a maintainer to add) the necessary Breaking* or New Feature labels where relevant.
• I have done my best to ensure that my PR adheres to the Fuel Labs Code Review Standards.
• I have requested a review from the relevant team or maintainers.

[kayagokalp]

Overall lgtm, left a single question just to make sure 👍

[kayagokalp]

Thanks for the fix, LGTM :)