From 4fa8b74dc7c4ccb367c794e84ec63fcdfc8d2dc1 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jonas=20=C3=85dahl?= <jadahl@gmail.com>
Date: Tue, 13 Dec 2016 11:45:43 +0800
Subject: [PATCH] monitor-unit-tests: Add musing about test declarations

https://bugzilla.gnome.org/show_bug.cgi?id=777732
---
 src/tests/monitor-unit-tests.c | 41 ++++++++++++++++++++++++++++++++++
 1 file changed, 41 insertions(+)

diff --git a/src/tests/monitor-unit-tests.c b/src/tests/monitor-unit-tests.c
index 6a1e6d476..6f4a2978e 100644
--- a/src/tests/monitor-unit-tests.c
+++ b/src/tests/monitor-unit-tests.c
@@ -34,6 +34,47 @@
 #define MAX_N_MONITORS 10
 #define MAX_N_LOGICAL_MONITORS 10
 
+/*
+ * The following structures are used to define test cases.
+ *
+ * Each test case consists of a test case setup and a test case expectaction.
+ * and a expected result, consisting
+ * of an array of monitors, logical monitors and a screen size.
+ *
+ * TEST CASE SETUP:
+ *
+ * A test case setup consists of an array of modes, an array of outputs and an
+ * array of CRTCs.
+ *
+ * A mode has a width and height in pixels, and a refresh rate in updates per
+ * second.
+ *
+ * An output has an array of available modes, and a preferred mode. Modes are
+ * defined as indices into the modes array of the test case setup.
+ *
+ * It also has CRTc and an array of possible CRTCs. Crtcs are defined as indices
+ * into the CRTC array. The CRTC value -1 means no CRTC.
+ *
+ * It also has various meta data, such as physical dimension, tile info and
+ * scale.
+ *
+ * A CRTC only has a current mode. A mode is defined as an index into the modes
+ * array.
+ *
+ *
+ * TEST CASE EXPECTS:
+ *
+ * A test case expects consists of an array of monitors, an array of logical
+ * monitors, a output and crtc count, and a screen width.
+ *
+ * A monitor represents a physical monitor (such as an external monitor, or a
+ * laptop panel etc). A monitor consists of an array of outputs, defined by
+ * indices into the setup output array, and the physical dimensions.
+ *
+ * A logical monitor represents a region of the total screen area. It contains
+ * the expected layout and a scale.
+ */
+
 typedef struct _MonitorTestCaseMode
 {
   int width;