Intro
Yesterday, pretty much out of nowhere, FCS 41.0.3 was published on NuGet. I must say, I’m pretty hyped about this release. It contains a few PRs that improve the syntax tree and provide more information to work within Fantomas.
It also contains some XML documentation improvements that Alex of the Rider team has been working on. You can read the details about this new XML collecting mechanism in this RFC. It is a nice improvement and I’ve decided to implement an enhancement in Fantomas due to these changes.
There actually are comments in the syntax tree
In the past, I had the luxury of speaking about Fantomas at conferences. In a lot of these talks, I explain how Fantomas works and rant a bit about code comments not being a part of the syntax tree. Now that isn’t exactly true. You see, at some very specific locations, triple-slash comments are preserved in the untyped syntax tree as PreXmlDoc.
We used to ignore this information in Fantomas, and capture those comments the same way we capture other types of comments. Which at the time seemed like the right thing to do. Now that the collection mechanism changed at the compiler side, we can start trusting those comments.
One less trivia
The more information we have in the untyped syntax tree, the better. So, we decide in Fantomas 4.7 to not accept triple-slash code comments as trivia comments anymore. This can lead to some unexpected situations. Triple slash comments are only collected by the F# parser at very specific locations.
One example is SynBinding:
In essence, every data type in SyntaxTree.fsi, that has a PreXmlDoc node can contain a triple-slash comment.
Awareness
This change in Fantomas 4.7 can be a bit impactful. I admit I got a bit carried away by the unexpected FCS release. I don’t regret this change and I believe it will educate end-users that there is a subtle difference between /// and // in FSharp code. But yes, depending on how you were using this, you might need to add a new entry in your .git-blame-ignore-revs file.
Cheers,
Florian
Photo by Fahrul Azmi on Unsplash