Doc updates (#5759)

* WIP

* WIP

5 files changed, 32 insertions, 9 deletions

diff --git a/docs/api/workers.md b/docs/api/workers.md
index 50fdb9c3d..2b8c4fe13 100644
--- a/docs/api/workers.md
+++ b/docs/api/workers.md
@@ -10,7 +10,7 @@ Bun implements a minimal version of the [Web Workers API](https://developer.mozi
 
 Like in browsers, [`Worker`](https://developer.mozilla.org/en-US/docs/Web/API/Worker) is a global. Use it to create a new worker thread.
 
-From the main thread:
+### From the main thread
 
 ```js#Main_thread
 const workerURL = new URL("worker.ts", import.meta.url).href;
@@ -22,16 +22,25 @@ worker.onmessage = event => {
 };
 ```
 
-Worker thread:
+### Worker thread
 
 ```ts#worker.ts_(Worker_thread)
+// prevents TS errors
+declare var self: Worker;
+
 self.onmessage = (event: MessageEvent) => {
   console.log(event.data);
   postMessage("world");
 };
 ```
 
-You can use `import`/`export` syntax in your worker code. Unlike in browsers, there's no need to specify `{type: "module"}` to use ES Modules.
+To prevent TypeScript errors when using `self`, add this line to the top of your worker file.
+
+```ts
+declare var self: Worker;
+```
+
+You can use `import` and `export` syntax in your worker code. Unlike in browsers, there's no need to specify `{type: "module"}` to use ES Modules.
 
 To simplify error handling, the initial script to load is resolved at the time `new Worker(url)` is called.
 
diff --git a/docs/bundler/index.md b/docs/bundler/index.md
index 8db531ce5..9b8029db1 100644
--- a/docs/bundler/index.md
+++ b/docs/bundler/index.md
@@ -29,6 +29,10 @@ The bundler is a key piece of infrastructure in the JavaScript ecosystem. As a b
 
 Let's jump into the bundler API.
 
+{% callout %}
+Note that the Bun bundler is not intended to replace `tsc` for typechecking or generating type declarations.
+{% /callout %}
+
 ## Basic example
 
 Let's build our first bundle. You have the following two files, which implement a simple client-side rendered React app.
diff --git a/docs/runtime/plugins.md b/docs/runtime/plugins.md
index 8f5bf21e2..a422fdc40 100644
--- a/docs/runtime/plugins.md
+++ b/docs/runtime/plugins.md
@@ -61,7 +61,7 @@ Plugins are primarily used to extend Bun with loaders for additional file types.
 ```ts#yamlPlugin.ts
 import { plugin } from "bun";
 
-plugin({
+await plugin({
   name: "YAML",
   async setup(build) {
     const { load } = await import("js-yaml");
@@ -84,15 +84,20 @@ plugin({
 });
 ```
 
-With this plugin, data can be directly imported from `.yaml` files.
+Register this file in `preload`:
+
+```toml#bunfig.toml
+preload = ["./yamlPlugin.ts"]
+```
+
+Once the plugin is registed, `.yaml` and `.yml` files can be directly imported.
 
 {% codetabs %}
 
 ```ts#index.ts
-import "./yamlPlugin.ts"
-import {name, releaseYear} from "./data.yml"
+import data from "./data.yml"
 
-console.log(name, releaseYear);
+console.log(data);
 ```
 
 ```yaml#data.yml
diff --git a/packages/bun-types/bun-test.d.ts b/packages/bun-types/bun-test.d.ts
index 03a067dc2..b32ffb4f7 100644
--- a/packages/bun-types/bun-test.d.ts
+++ b/packages/bun-types/bun-test.d.ts
@@ -114,7 +114,7 @@ declare module "bun:test" {
   export function spyOn<T extends object, K extends keyof T>(
     obj: T,
     methodOrPropertyValue: K,
-  ): Mock<() => T[K]>;
+  ): Mock<T[K] extends AnyFunction ? T[K] : never>;
 
   /**
    * Describes a group of related tests.
diff --git a/packages/bun-types/tests/test.test-d.ts b/packages/bun-types/tests/test.test-d.ts
index 1d504272d..831b18e2e 100644
--- a/packages/bun-types/tests/test.test-d.ts
+++ b/packages/bun-types/tests/test.test-d.ts
@@ -6,7 +6,12 @@ import {
   afterAll,
   beforeEach,
   afterEach,
+  spyOn,
 } from "bun:test";
+import { expectType } from "tsd";
+
+const spy = spyOn(console, "log");
+expectType<any[][]>(spy.mock.calls);
 
 const hooks = [beforeAll, beforeEach, afterAll, afterEach];