From f2a60e4220fedceac29578a90d2c1e8bf5844399 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Fr=C3=A9d=C3=A9ric=20Mangano-Tarumi?= <fmang@mg0.fr>
Date: Sun, 4 Nov 2018 17:47:50 -0500
Subject: [PATCH] overall documentation for opus.cc

---
 src/opus.cc    | 24 ++++++++++++++++++++++++
 src/opustags.h |  5 +++++
 2 files changed, 29 insertions(+)

diff --git a/src/opus.cc b/src/opus.cc
index 0a882bc..a584a11 100644
--- a/src/opus.cc
+++ b/src/opus.cc
@@ -1,3 +1,27 @@
+/**
+ * \file src/opus.cc
+ * \ingroup opus
+ *
+ * The way Opus is encapsulated into an Ogg stream, and the content of the packets we're dealing
+ * with here is defined by [RFC 7584](https://tools.ietf.org/html/rfc7845.html).
+ *
+ * Section 3 "Packet Organization" is critical for us:
+ *
+ * - The first page contains exactly 1 packet, the OpusHead, and it contains it entirely.
+ * - The second page begins the OpusTags packet, which may span several pages.
+ * - The OpusTags packet must finish the page on which it completes.
+ *
+ * The structure of the OpusTags packet is defined in section 5.2 "Comment Header" of the RFC.
+ *
+ * OpusTags is similar to [Vorbis Comment](https://www.xiph.org/vorbis/doc/v-comment.html), which
+ * gives us some context, but let's stick to the RFC for the technical details.
+ *
+ * \todo Validate that the vendor string and comments are valid UTF-8.
+ * \todo Validate that field names are ASCII: 0x20 through 0x7D, 0x3D ('=') excluded.
+ * \todo Field names are case insensitive, respect that.
+ *
+ */
+
 #include "opustags.h"
 
 #include <cstdlib>
diff --git a/src/opustags.h b/src/opustags.h
index 5e82693..a8549c6 100644
--- a/src/opustags.h
+++ b/src/opustags.h
@@ -27,6 +27,11 @@ int write_page(ogg_page *og, FILE *stream);
  * \{
  */
 
+/**
+ * Represent all the data in an OpusTags packet.
+ *
+ * \todo The comment list may be followed by arbitrary binary data, which we should keep here.
+ */
 struct opus_tags {
 	uint32_t vendor_length;
 	const char *vendor_string;