From 9194d6c496c56a680fb6010ae52cfaf8bdc53343 Mon Sep 17 00:00:00 2001
From: Mitchell Hashimoto <m@mitchellh.com>
Date: Mon, 6 Oct 2025 08:36:19 -0700
Subject: [PATCH] doxygen: integrate examples into documentation

---
 Doxyfile                               |  3 +++
 include/ghostty/vt.h                   | 25 +++++++++++++++++++++----
 src/build/docker/lib-c-docs/Dockerfile |  1 +
 3 files changed, 25 insertions(+), 4 deletions(-)

diff --git a/Doxyfile b/Doxyfile
index 0c8688987..58b6be48a 100644
--- a/Doxyfile
+++ b/Doxyfile
@@ -6,6 +6,9 @@ PROJECT_LOGO           = images/gnome/64.png
 INPUT                  = include/ghostty/vt.h
 INPUT_ENCODING         = UTF-8
 RECURSIVE              = NO
+EXAMPLE_PATH           = example
+EXAMPLE_RECURSIVE      = YES
+EXAMPLE_PATTERNS       = *
 FULL_PATH_NAMES        = NO
 STRIP_FROM_INC_PATH    = include
 SOURCE_BROWSER         = YES
diff --git a/include/ghostty/vt.h b/include/ghostty/vt.h
index ebb41e300..bcbb01d00 100644
--- a/include/ghostty/vt.h
+++ b/include/ghostty/vt.h
@@ -1,7 +1,7 @@
 /**
  * @file vt.h
  *
- * libghostty-vt - Virtual terminal sequence parsing library
+ * libghostty-vt - Virtual terminal emulator library
  * 
  * This library provides functionality for parsing and handling terminal
  * escape sequences as well as maintaining terminal state such as styles,
@@ -12,14 +12,15 @@
  */
 
 /**
- * @mainpage libghostty-vt - Virtual Terminal Sequence Parser
+ * @mainpage libghostty-vt - Virtual Terminal Emulator Library
  *
  * libghostty-vt is a C library which implements a modern terminal emulator,
  * extracted from the [Ghostty](https://ghostty.org) terminal emulator.
  *
  * libghostty-vt contains the logic for handling the core parts of a terminal
- * emulator: parsing terminal escape sequences and maintaining terminal state.
- * It can handle scrollback, line wrapping, reflow on resize, and more.
+ * emulator: parsing terminal escape sequences, maintaining terminal state,
+ * encoding input events, etc. It can handle scrollback, line wrapping, 
+ * reflow on resize, and more.
  *
  * @warning This library is currently in development and the API is not yet stable.
  * Breaking changes are expected in future versions. Use with caution in production code.
@@ -31,6 +32,22 @@
  * - @ref osc "OSC Parser" - Parse OSC (Operating System Command) sequences
  * - @ref allocator "Memory Management" - Memory management and custom allocators
  *
+ * @section examples_sec Examples
+ *
+ * Complete working examples:
+ * - @ref c-vt/src/main.c - OSC parser example
+ * - @ref c-vt-key-encode/src/main.c - Key encoding example
+ *
+ */
+
+/** @example c-vt/src/main.c
+ * This example demonstrates how to use the OSC parser to parse an OSC sequence,
+ * extract command information, and retrieve command-specific data like window titles.
+ */
+
+/** @example c-vt-key-encode/src/main.c
+ * This example demonstrates how to use the key encoder to convert key events
+ * into terminal escape sequences using the Kitty keyboard protocol.
  */
 
 #ifndef GHOSTTY_VT_H
diff --git a/src/build/docker/lib-c-docs/Dockerfile b/src/build/docker/lib-c-docs/Dockerfile
index 8b4f2f6df..a3cfdcc98 100644
--- a/src/build/docker/lib-c-docs/Dockerfile
+++ b/src/build/docker/lib-c-docs/Dockerfile
@@ -14,6 +14,7 @@ WORKDIR /ghostty
 COPY include/ ./include/
 COPY images/ ./images/
 COPY dist/doxygen/ ./dist/doxygen/
+COPY example/ ./example/
 COPY Doxyfile ./
 COPY DoxygenLayout.xml ./
 RUN mkdir -p zig-out/share/ghostty/doc/libghostty
-- 
2.51.2