refactor(ast_codegen): use doc comments instead of insert!

[overlookmotel]

Avoid the insert! macro in AST codegen. Use doc comments starting with special symbol @ instead.

• Before: insert!("// plain comment");
• After: ///@ plain comment
• Or: //!@ plain comment

Either ///@ or //!@ is converted to plain // in output.

//!@ is legal in top-of-file position, which allows us to inline #![allow(...)] attributes, which in my opinion makes the generators a bit easier to read.

[overlookmotel]

• refactor(ast_codegen): replace ///@@ with ///@@line_break #4786
• refactor(ast_codegen): trim r# from start of field names #4785
• refactor(ast_codegen): alter JSON schema format #4784
• refactor(ast_codegen): remove excess space from start of doc comments #4782
• refactor(ast_codegen): line breaks between types in layout assertions #4781
• refactor(ast_codegen): re-order code in fmt module #4779
• refactor(ast_codegen): use doc comments instead of endl! #4778
• refactor(ast_codegen): use doc comments instead of insert! #4777 👈
• refactor(ast_codegen): move formatting regex definitions #4775
• refactor(ast_codegen): remove unnecessary imports from generated files #4774
• refactor(ast): oxc_ast crate re-export AST types from other crates #4773
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

Join @overlookmotel and the rest of your teammates on Graphite

[graphite-app]

Your org has enabled the Graphite merge queue for merging into main

Add the label “merge” to the PR and Graphite will automatically add it to the merge queue when it’s ready to merge. Or use the label “hotfix” to add to the merge queue as a hot fix.

You must have a Graphite account and log in to Graphite in order to use the merge queue. Sign up using this link.

[overlookmotel]

@rzvxa The @ symbol is a bit mysterious, so not ideal, but on balance I think it's preferable to the harder-to-read insert!(). What do you think?

[codspeed-hq]

CodSpeed Performance Report

Merging #4777 will not alter performance

_{Comparing 08-09-refactor_ast_codegen_use_doc_comments_instead_of_insert_ (f418f62) with main (b22ed45)}

Summary

✅ 29 untouched benchmarks

[rzvxa]

To be honest I don't like this change, It is too complicated for a simple thing.
I prefer the syntax noise over having too many symbols.

With that said, Feel free to merge as you wish.

[overlookmotel]

To be honest I don't like this change, It is too complicated for a simple thing. I prefer the syntax noise over having too many symbols.

With that said, Feel free to merge as you wish.

OK. My feeling is that it's worth it for making generators/visit.rs clearer.

Since you've given me permission to merge, I'm going to do that.

[graphite-app]

Merge activity

• Aug 9, 4:18 AM EDT: The merge label 'merge' was detected. This PR will be added to the Graphite merge queue once it meets the requirements.
• Aug 9, 4:18 AM EDT: overlookmotel added this pull request to the Graphite merge queue.
• Aug 9, 4:22 AM EDT: overlookmotel merged this pull request with the Graphite merge queue.