From b1a7b8019fe5eed831646d4e64d03abc15d9fd90 Mon Sep 17 00:00:00 2001
From: Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
Date: Thu, 2 Aug 2018 18:47:06 +0200
Subject: [PATCH] media_element: Document this module.

---
 src/media_element.rs | 24 ++++++++++++++++++++++--
 1 file changed, 22 insertions(+), 2 deletions(-)

diff --git a/src/media_element.rs b/src/media_element.rs
index 9b9133c..b74e7f9 100644
--- a/src/media_element.rs
+++ b/src/media_element.rs
@@ -4,21 +4,41 @@
 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at http://mozilla.org/MPL/2.0/.
 
+#![deny(missing_docs)]
+
 use helpers::TrimmedPlainText;
 
-generate_element_with_text!(URI, "uri", MEDIA_ELEMENT,
+generate_element_with_text!(
+    /// Represents an URI used in a media element.
+    URI, "uri", MEDIA_ELEMENT,
     [
+        /// The MIME type of the URI referenced.
+        ///
+        /// See the [IANA MIME Media Types Registry][1] for a list of
+        /// registered types, but unregistered or yet-to-be-registered are
+        /// accepted too.
+        ///
+        /// [1]: https://www.iana.org/assignments/media-types/media-types.xhtml
         type_: String = "type" => required
     ],
+
+    /// The actual URI contained.
     uri: TrimmedPlainText<String>
 );
 
-generate_element!(MediaElement, "media", MEDIA_ELEMENT,
+generate_element!(
+    /// References a media element, to be used in [data
+    /// forms](../data_forms/index.html).
+    MediaElement, "media", MEDIA_ELEMENT,
     attributes: [
+        /// The recommended display width in pixels.
         width: Option<usize> = "width" => optional,
+
+        /// The recommended display height in pixels.
         height: Option<usize> = "height" => optional
     ],
     children: [
+        /// A list of URIs referencing this media.
         uris: Vec<URI> = ("uri", MEDIA_ELEMENT) => URI
     ]
 );