doc(swc_common): Document error reporting using HANDLER (#3605)

crates/swc_common/src/errors/mod.rs

@@ -304,6 +304,43 @@ impl error::Error for ExplicitBug {
 /// A handler deals with errors; certain errors
 /// (fatal, bug, unimpl) may cause immediate exit,
 /// others log errors for later reporting.
+///
+/// # Example
+///
+/// `swc` provides a global-like variable ([HANDLER]) of type `Handler` that can
+/// be used to report errors.
+///
+/// You can refer to [the lint rules](https://github.com/swc-project/swc/tree/main/crates/swc_ecma_lints/src/rules) for other example usages.
+/// All lint rules have code for error reporting.
+///
+/// ## Error reporting in swc
+///
+/// ```rust,ignore
+/// use swc_common::errors::HANDLER;
+///
+/// # fn main() {
+///     HANDLER.with(|handler| {
+///         // You can access the handler for the current file using HANDLER.with.
+///
+///         // We now report an error
+///
+///         // `struct_span_err` creates a builder for a diagnostic.
+///         // The span passed to `struct_span_err` will used to point the problematic code.
+///         //
+///         // You may provide additional information, like a previous declaration of parameter.
+///         handler
+///             .struct_span_err(
+///                 span,
+///                 &format!("`{}` used as parameter more than once", js_word),
+///             )
+///             .span_note(
+///                 old_span,
+///                 &format!("previous definition of `{}` here", js_word),
+///             )
+///             .emit();
+///     });
+/// # }
+/// ```
 pub struct Handler {
     pub flags: HandlerFlags,
 
@@ -907,5 +944,7 @@ scoped_thread_local!(
     /// e.g.
     ///  - `parser` should not use this.
     ///  - `transforms` should use this to report error, as it does not return [Result].
+    ///
+    /// See [Handler] for actual usage examples.
     pub static HANDLER: Handler
 );