node-osc/docs/README.md

pyOSC inspired library for sending and receiving OSC messages

# node-osc Documentation

Welcome to the node-osc documentation! This directory contains comprehensive documentation for the node-osc library.

## Documentation Overview

### 📚 [API Reference](./API.md)
**Complete API documentation for all classes and functions**

Auto-generated from JSDoc comments in the source code. This is your reference for:
- All classes: `Server`, `Client`, `Message`, `Bundle`
- All methods and their parameters
- Low-level functions: `encode()` and `decode()`
- Return types and error conditions
- Code examples for each API

> **Note:** This file is automatically generated. To update it, edit the JSDoc comments in the source code and run `npm run docs`.

### 📘 [Usage Guide](./GUIDE.md)
**Best practices, patterns, and troubleshooting**

A comprehensive guide covering:
- Event handling patterns
- Error handling strategies
- OSC type system details
- Best practices for production use
- Troubleshooting common issues
- Advanced topics like custom transports and performance optimization

## Quick Navigation

**New to node-osc?**
1. Start with the [main README](../README.md) for a quick introduction and installation
2. Try the [examples](../examples/) to see working code
3. Read the [Usage Guide](./GUIDE.md) to learn best practices
4. Reference the [API documentation](./API.md) as needed

**Looking for something specific?**
- **How to send/receive messages** → [API Reference](./API.md) (Server and Client sections)
- **How to handle errors** → [Usage Guide](./GUIDE.md#error-handling)
- **Type system and data types** → [Usage Guide](./GUIDE.md#type-system)
- **Working with bundles** → [API Reference](./API.md#bundle)
- **Troubleshooting** → [Usage Guide](./GUIDE.md#troubleshooting)
- **Code examples** → [Examples directory](../examples/)
- **Advanced use cases** → [Usage Guide](./GUIDE.md#advanced-topics)

## Additional Resources

- **[Examples](../examples/)** - Working code examples for various use cases
- **[Main README](../README.md)** - Quick start and project overview
- **[OSC Specification](http://opensoundcontrol.org/spec-1_0)** - Official OSC protocol documentation

## Contributing to Documentation

### Updating API Documentation

The API documentation is automatically generated from JSDoc comments:

1. Edit JSDoc comments in the source files (`lib/**/*.mjs`)
2. Run `npm run docs` to regenerate `API.md`
3. Review the changes and commit

### Updating the Usage Guide

The Usage Guide (`GUIDE.md`) is manually maintained. When editing:

- Keep it focused on patterns, best practices, and how-to content
- Avoid duplicating API details (link to API.md instead)
- Include practical code examples
- Update the table of contents if adding new sections

## Documentation Structure Philosophy

Our documentation is organized to minimize duplication while maximizing usefulness:

- **README.md** (main) → Quick start, basic examples, installation
- **API.md** → Complete API reference with all technical details
- **GUIDE.md** → How to use the library effectively, patterns, and troubleshooting
- **examples/** → Working code you can run and learn from

This structure ensures you can find what you need without reading through repeated content.