doc(es/ast): Improve rustdoc (#3142)

swc_ecma_ast:
 - Document `Str.kind`.
 - Document `TpleElement.cooked`.

crates/swc_ecma_ast/src/expr.rs

@@ -642,6 +642,12 @@ impl Take for TaggedTpl {
 pub struct TplElement {
     pub span: Span,
     pub tail: bool,
+
+    /// This value is never used by `swc_ecma_codegen`, and this fact is
+    /// considered as a public API.
+    ///
+    /// If you are going to use codegen right after creating a [TplElement], you
+    /// don't have to worry about this value.
     pub cooked: Option<Str>,
     pub raw: Str,
 }

crates/swc_ecma_ast/src/lit.rs

@@ -53,6 +53,16 @@ impl<'a> arbitrary::Arbitrary<'a> for BigInt {
     }
 }
 
+/// A string literal.
+///
+/// # Note
+///
+/// You have to use [StrKind::Synthesized] if you modify the `value` of [Str].
+/// This behavior is for preserving the original source code.
+///
+/// In other words, `swc_ecma_codegen` tries to preserve escapes or unicode
+/// characters in the original source code and you can opt-out of this by using
+/// [StrKind::Synthesized].
 #[ast_node("StringLiteral")]
 #[derive(Eq, Hash, EqIgnoreSpan)]
 pub struct Str {

crates/swc_ecma_transforms_module/src/rewriter.rs

@@ -47,6 +47,8 @@ where
                                     })
                                     .unwrap();
 
+                                // This string literal is synthesized
+                                s.kind = Default::default();
                                 s.value = src;
                             }
                             _ => {}

crates/swc_ecma_transforms_typescript/examples/ts_to_js.rs

@@ -8,7 +8,7 @@ use swc_common::{
     comments::SingleThreadedComments,
     errors::{ColorConfig, Handler},
     sync::Lrc,
-    Mark, SourceMap,
+    Globals, Mark, SourceMap, GLOBALS,
 };
 use swc_ecma_codegen::{text_writer::JsWriter, Emitter};
 use swc_ecma_parser::{lexer::Lexer, Parser, StringInput, Syntax, TsConfig};
@@ -56,6 +56,8 @@ fn main() {
         .map_err(|e| e.into_diagnostic(&handler).emit())
         .expect("failed to parse module.");
 
+    let globals = Globals::default();
+    GLOBALS.set(&globals, || {
         let top_level_mark = Mark::fresh(Mark::root());
 
         // Optionally transforms decorators here before the resolver pass
@@ -86,4 +88,5 @@ fn main() {
         }
 
         println!("{}", String::from_utf8(buf).expect("non-utf8?"));
+    })
 }