@ahoppen I've really done my best to accommodate all your comments and address them all. But please note that, like I've mentioned in my initial comment on this PR, I'm having a hard time finding the right places in the CodeGeneration package to place the documentation comments. I have now done my best to find the right places and add the documentation code to the type, which I could find some of, but it was a very time-consuming task.

But there were a few reuses of some comments in multiples places (such as StringSegmentSyntax once for the type and once for the enum case), although they should probably be more detailed in the type and shorter for the case.

But most importantly, pretty much ALL of my provided documentation comments for any initializers I couldn't find a place to add them in the CodeGeneration package. It doesn't seem to be trivial to add documentation comments, which is a bummer. If you checkout my branch and run swift run generate-swift-syntax from the CodeGeneration folder, you'll see in the git diff all the initializers that are missing their documentation (and few other things).

If you can guide me how to add documentation comments for those, e.g. by giving an example for one of those, I might be able to get more comments into the CodeGeneration package. For now, this is all I could do.

Thanks for your effort @Jeehut.

The initializers are generated here.

I didn’t check all the comments you wrote on initializers but I think we should be able to re-use some of the existing infrastructure to generate them:

• Comments for the parameters (eg. https://github.com/swiftlang/swift-syntax/pull/2922/files#diff-c5a0310c344fd64bfa2e1a25205f2faa3ee2a6f2a77686ada19dd4bfa8e40842R671): If you add those comments to the the corresponding Child types in SyntaxSupport, they should automatically show up
• Documentation for unexpected*. I wonder if we could automatically generate them based on the information that we have.
• The documentation for the conversion initializer should be possible to add to all init?(_ node: __shared some SyntaxProtocol) initializers
• The remaining hand-written initializer comments might make sense to put on the type themselves. Alternatively, we could add a field to Node and then pass that through InitSignature to add it the generated memberwise initializer. But if there’s a way to generate equivalent information using the fields we already have, I would prefer that because it’s less maintenance burden.