From badcc8fba22cb0a2485e3099ebc267707cf6413d Mon Sep 17 00:00:00 2001
From: Sebastian Norling <1932208+Bazze@users.noreply.github.com>
Date: Thu, 21 May 2026 15:19:15 +0200
Subject: [PATCH] docs(development): point readers at event/stream higher-level
 helper
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Development.md describes the wire-layer convention (one directory per
Onvif Web Service, gen_commands.py for new SOAP command types) but
does not mention that some directories also ship hand-written
higher-level helpers built on top of those types. A new contributor
reading the doc could reasonably assume event/ is purely
auto-generated and miss event/stream.

Adds a 'Higher-level helpers' section that calls out:
* event/stream — the new channel-based event consumer.
* event/topic — the existing topic identifier helpers.

Also documents the placement convention (sub-package under the
relevant web service directory) so future helpers land in a
predictable spot.
---
 docs/Development.md | 20 ++++++++++++++++++++
 1 file changed, 20 insertions(+)

diff --git a/docs/Development.md b/docs/Development.md
index 4d5cdaf..74420fc 100644
--- a/docs/Development.md
+++ b/docs/Development.md
@@ -32,3 +32,23 @@ python3 python/gen_commands.py
 
 > **Note:** You can also typically run the generator within your IDE thanks to the `//go:generate` lines 
 > towards the top of the `types.go` files.
+
+## Higher-level helpers
+
+Some web service directories ship hand-written, higher-level helpers
+built on top of the wire-layer commands. These are normal Go packages
+— **not** covered by the `gen_commands.py` workflow above and not
+expected to be regenerated.
+
+- [event/stream](../event/stream) — channel-based event consumer that
+  owns the pull-point subscription lifecycle (Create, Pull, Renew,
+  Unsubscribe, reconnect with jittered backoff) and decodes
+  notifications into normalized typed Events. Vendor topic strings
+  (AXIS, Hikvision, Avigilon, Hanwha, Bosch, Dahua) are classified
+  into a small set of `Kind` values. See the package `doc.go` for the
+  public surface and usage.
+- [event/topic](../event/topic) — topic identifier helpers.
+
+When adding a similar higher-level helper, place it under the relevant
+web service directory as a sub-package so consumers find it next to
+the wire-layer types it builds on.