docs: ✏️ move documentation to docblocks

Author: lrodrigues-newstore

packages/emitter/README.md

@@ -12,51 +12,6 @@ Minimalistic event emitter.
 yarn add @pacote/emitter
 ```
 
-## Usage
-
-```typescript
-import { createEmitter } from '@pacote/emitter'
-
-const emitter = createEmitter()
-
-emitter.on('greet', () => console.log('Hello, world!'))
-emitter.emit('greet') // => 'Hello, world!'
-```
-
-### `createEmitter<Events>(): Emitter<Events>`
-
-`createEmitter()` creates a new instance of an event emitter that provides the following methods:
-
-#### `.on(name: string, fn: (...args: any[]): void): () => void`
-
-Binds the `fn` callback to an event with the supplied name.
-
-The method returns a function that unbinds the callback, preventing it from being called again.
-
-```typescript
-const emitter = createEmitter()
-
-const unbind = emitter.on('greet', () => console.log('Hello, world!'))
-
-emitter.emit('greet') // triggers the callback
-
-unbind()
-
-emitter.emit('greet') // no longer triggers the callback
-```
-
-#### `.emit(name: string, ...args: any[]): void`
-
-Fires the named event, triggering any subscribers previously bound to it using the `.on()` method. Arguments provided after the name are passed to the callback function.
-
-```typescript
-const emitter = createEmitter()
-
-emitter.on('greet', (name) => console.log(`Hello, ${name}!`))
-
-emitter.emit('greet', 'TypeScript') // => 'Hello, TypeScript!'
-```
-
 ## License
 
 MIT © [Luís Rodrigues](https://goblindegook.com).

packages/emitter/src/index.ts

@@ -5,10 +5,65 @@ interface Events {
 }
 
 interface Emitter<E extends Events> {
+  /**
+   * Binds a subscriber function to an event with the supplied name.
+   *
+   * @param name Event name.
+   * @param fn   Subscriber to invoke when the event is emitted.
+   *
+   * @returns Function to unbind the event.
+   *
+   * @example
+   *
+   * ```typescript
+   * const emitter = createEmitter()
+   * const unbind = emitter.on('greet', () => console.log('Hello, world!'))
+   *
+   * emitter.emit('greet') // triggers the callback
+   *
+   * unbind()
+   *
+   * emitter.emit('greet') // no longer triggers the callback
+   * ```
+   */
   on<K extends keyof E>(name: K, fn: E[K]): () => void
+
+  /**
+   * Fires the named event, triggering any subscribers previously bound to
+   * it using the `.on()` method. Arguments provided after the name are
+   * passed to the subscriber function.
+   *
+   * @param name Event name.
+   * @param args Optional subscriber parameters.
+   *
+   * @example
+   *
+   * ```typescript
+   * const emitter = createEmitter()
+   *
+   * const unbind = emitter.on('greet', (name) => console.log(`Hello, ${name}!`))
+   *
+   * emitter.emit('greet', 'Pacote') // => 'Hello, Pacote!'
+   * ```
+   */
   emit<K extends keyof E>(name: K, ...args: Parameters<E[K]>): void
 }
 
+/**
+ * Creates a new instance of an event emitter.
+ *
+ * @returns Event emitter.
+ *
+ * @example
+ *
+ * ```typescript
+ * import { createEmitter } from '@pacote/emitter'
+ *
+ * const emitter = createEmitter()
+ * emitter.on('greet', () => console.log('Hello, world!'))
+ * emitter.emit('greet') // => 'Hello, world!'
+ * ```
+ */
 export function createEmitter<E extends Events>(): Emitter<E> {
   const events: Partial<{ [K in keyof E]: E[K][] }> = {}