chore(napi): Add README explainer for cli/napi_sym and cli/napi (#16187)

1 files changed, 34 insertions, 0 deletions

diff --git a/cli/napi_sym/README.md b/cli/napi_sym/README.md
new file mode 100644
index 000000000..80bb2be0f
--- /dev/null
+++ b/cli/napi_sym/README.md
@@ -0,0 +1,34 @@
+# napi_sym
+
+A proc_macro for Deno's Node-API implementation. It does the following things:
+
+- Marks the symbol as `#[no_mangle]` and rewrites it as `pub extern "C" $name`.
+- Asserts that the function symbol is present in
+  [`symbol_exports.json`](./symbol_exports.json).
+- Maps `deno_napi::Result` to raw `napi_result`.
+
+```rust
+use deno_napi::{napi_value, Env, Error, Result};
+
+#[napi_sym::napi_sym]
+fn napi_get_boolean(
+  env: *mut Env,
+  value: bool,
+  result: *mut napi_value,
+) -> Result {
+  let _env: &mut Env = env.as_mut().ok_or(Error::InvalidArg)?;
+  // *result = ...
+  Ok(())
+}
+```
+
+### `symbol_exports.json`
+
+A file containing the symbols that need to be put into the exectable's dynamic
+symbol table at link-time.
+
+This is done using `/DEF:` on Windows, `-exported_symbol,_` on macOS and
+`--export-dynamic-symbol=` on Linux. See [`cli/build.rs`](../build.rs).
+
+On Windows, you need to generate the `.def` file by running
+[`tools/napi/generate_link_win.js`](../../tools/napi/generate_link_win.js).