From 2b13a2beff8de8ccccc5a8312f346a7ee3753c87 Mon Sep 17 00:00:00 2001
From: Sebastian Hugentobler <sebastian@vanwa.ch>
Date: Thu, 22 Jun 2017 09:20:47 +0200
Subject: [PATCH] document the cd key extraction process

---
 src/models/content.rs | 34 ++++++++++++++++++++++++++++++++++
 1 file changed, 34 insertions(+)

diff --git a/src/models/content.rs b/src/models/content.rs
index b8a506d..f4f4898 100644
--- a/src/models/content.rs
+++ b/src/models/content.rs
@@ -52,6 +52,40 @@ fn deserialize_title<D>(deserializer: D) -> Result<String, D::Error>
     Ok(title_whitespace)
 }
 
+/// Keys come in at least three different forms.
+/// It is possible to parse them all into the same structure, a map.
+///
+/// # Variants
+/// ## I
+/// Only one key and the value is the key itself.
+/// `1234-5678-1234-5678`
+///
+/// ## II
+/// Multiple keys split at single `<br>` tags with the key name and value itself
+/// split at `:<br>`.
+/// ```
+/// Neverwinter Nights:<br>	1234-5678-1234-5678	<br>Shadows of Undrentide:<br>	1234-5678-1234-5678	<br>Hordes of the Underdark:<br>	1234-5678-1234-5678
+/// ```
+///
+/// ## III
+/// Multiple keys split at `</span><span>` tags with the key name and value itself
+/// again split at `:<br>`.
+///
+/// ```
+/// <span>Neverwinter Nights 2:<br>1234-5678-1234-5678</span><span>Mask of the Betrayer:<br>1234-5678-1234-5678</span><span>Storm of Zehir:<br>1234-5678-1234-5678</span>
+/// ```
+///
+/// With this information the method works as follows:
+/// - replace every `</span><span>` with `:`
+/// - remove every `<span>` and `</span>`
+/// - replace every `<br>` with `:`
+/// - replace every `::` with `:`
+/// - if there is at least one `:`
+///     - split at `:`
+///     - every odd position in the resulting array is a key name, every even its corresponding value
+/// - if not
+///     - the content name is the key name and the value is used as is
+///
 fn deserialize_cd_keys(content_title: &str, raw_cd_keys: &str) -> BTreeMap<String, String> {
     let mut cd_keys = BTreeMap::new();
     let mut raw_cd_keys_fix = raw_cd_keys.to_owned();