fix(Symbol): deprecate for_global in favour of for_key and for_api (#1324)

`for_global` was documented as `for_key` but implemented as `for_api`.

Closes #1323

src/symbol.rs

@@ -10,6 +10,10 @@ extern "C" {
     isolate: *mut Isolate,
     description: *const String,
   ) -> *const Symbol;
+  fn v8__Symbol__For(
+    isolate: *mut Isolate,
+    description: *const String,
+  ) -> *const Symbol;
   fn v8__Symbol__ForApi(
     isolate: *mut Isolate,
     description: *const String,
@@ -58,6 +62,38 @@ impl Symbol {
   /// To minimize the potential for clashes, use qualified descriptions as keys.
   /// Corresponds to v8::Symbol::For() in C++.
   #[inline(always)]
+  pub fn for_key<'s>(
+    scope: &mut HandleScope<'s, ()>,
+    description: Local<String>,
+  ) -> Local<'s, Symbol> {
+    unsafe {
+      scope
+        .cast_local(|sd| v8__Symbol__For(sd.get_isolate_ptr(), &*description))
+    }
+    .unwrap()
+  }
+
+  /// Retrieve a global symbol. Similar to `for_key`, but using a separate
+  /// registry that is not accessible by (and cannot clash with) JavaScript code.
+  /// Corresponds to v8::Symbol::ForApi() in C++.
+  #[inline(always)]
+  pub fn for_api<'s>(
+    scope: &mut HandleScope<'s, ()>,
+    description: Local<String>,
+  ) -> Local<'s, Symbol> {
+    unsafe {
+      scope.cast_local(|sd| {
+        v8__Symbol__ForApi(sd.get_isolate_ptr(), &*description)
+      })
+    }
+    .unwrap()
+  }
+
+  #[deprecated(
+    since = "0.77.0",
+    note = "This was documented as `for_key` but implemented as `for_api`"
+  )]
+  #[inline(always)]
   pub fn for_global<'s>(
     scope: &mut HandleScope<'s, ()>,
     description: Local<String>,

tests/test_api.rs

@@ -7374,14 +7374,24 @@ fn symbol() {
   let s = v8::Symbol::new(scope, Some(desc));
   assert!(s.description(scope) == desc);
 
-  let s_pub = v8::Symbol::for_global(scope, desc);
+  let s_pub = v8::Symbol::for_key(scope, desc);
   assert!(s_pub.description(scope) == desc);
   assert!(s_pub != s);
 
-  let s_pub2 = v8::Symbol::for_global(scope, desc);
+  let s_pub2 = v8::Symbol::for_key(scope, desc);
   assert!(s_pub2 != s);
   assert!(s_pub == s_pub2);
 
+  let s_api = v8::Symbol::for_api(scope, desc);
+  assert!(s_api.description(scope) == desc);
+  assert!(s_api != s);
+  assert!(s_api != s_pub);
+
+  let s_api2 = v8::Symbol::for_api(scope, desc);
+  assert!(s_api2 != s);
+  assert!(s_api2 != s_pub);
+  assert!(s_api == s_api2);
+
   let context = v8::Context::new(scope);
   let scope = &mut v8::ContextScope::new(scope, context);