Skip to content

Developer documentation: how to build an OST module (dev-module section)

The "dev-module" section of the public documentation (documentation/content/dev/dev-module/) is currently an empty stub marked obsolete ("this section is not up to date, content needs to be fully redone"), with nothing else under it. There is no developer-facing documentation at all on how to build a new OST module from scratch.

Plan (phased, builds on existing groundwork already drafted/validated in this project's internal notes):

  1. Survey ALL existing modules, not a sample - every module under src/modules/, no exceptions - to find where construction conventions actually diverge (naming, JSON property schema usage, directedit/permission patterns, status handling, device/slave guards, action button handling, INDI vs non-INDI structure). Deliberately broad: different module functions need different resources, and narrowing the sample up front would hide exactly the divergences this chantier exists to find. Partially overlaps with and complements the already-completed behavioral audit from issue #237 (closed) (status/device-guard/action-button homogenization) - this pass goes wider, covering structural/JSON conventions too.
  2. Rewrite dummy into a clean, working feature catalogue - one property group per concept to be taught (types, permission, directedit, autoupdate, bool group rules, LOV scopes, grids, profiles, graphs, inter-module communication, INDI specifics, i18n logs), each with real working C++ behind it. dummy today has 31 inconsistently-named properties and a mostly-commented-out event handler - not usable as a living reference as-is.
  3. Write the dev-module documentation using the rewritten dummy as the living, runnable reference for every example.
  4. Validate by testing it on a neophyte: hand the repo and the finished documentation to a fresh agent with no other context, and ask it to build a brand new, trivial OST module end to end (same method already used successfully for the client-protocol documentation, issues #207 (closed)-#216 (closed)). Every point of confusion is a direct signal of a documentation gap, to fix by iterating rather than guessing what a newcomer needs up front.

Each phase will get its own more narrowly scoped issue/branch as work on it starts; this issue tracks the overall initiative.