From 11ac527fca20311444923b11c147a7f41b3004f5 Mon Sep 17 00:00:00 2001
From: Luro02 <24826124+Luro02@users.noreply.github.com>
Date: Mon, 24 Feb 2020 14:28:14 +0100
Subject: [PATCH] improve documentation of EncryptionMethod

---
 src/types/encryption_method.rs | 50 ++++++++++++++++++----------------
 1 file changed, 27 insertions(+), 23 deletions(-)

diff --git a/src/types/encryption_method.rs b/src/types/encryption_method.rs
index 6d4f1ea..1dd977c 100644
--- a/src/types/encryption_method.rs
+++ b/src/types/encryption_method.rs
@@ -1,43 +1,46 @@
 use strum::{Display, EnumString};
 
-/// Encryption method.
-///
-/// See: [4.3.2.4. EXT-X-KEY]
-///
-/// [4.3.2.4. EXT-X-KEY]: https://tools.ietf.org/html/rfc8216#section-4.3.2.4
+/// The encryption method.
 #[non_exhaustive]
 #[allow(missing_docs)]
 #[derive(Ord, PartialOrd, Debug, Clone, Copy, PartialEq, Eq, Hash, Display, EnumString)]
 #[strum(serialize_all = "SCREAMING-KEBAB-CASE")]
 pub enum EncryptionMethod {
-    /// `None` means that the [`MediaSegment`]s are not encrypted.
+    /// The [`MediaSegment`]s are not encrypted.
     ///
     /// [`MediaSegment`]: crate::MediaSegment
     None,
-    /// `Aes128` signals that the [`MediaSegment`]s are completely encrypted
-    /// using the Advanced Encryption Standard ([AES-128]) with a 128-bit
-    /// key, Cipher Block Chaining (CBC), and
-    /// [Public-Key Cryptography Standards #7 (PKCS7)] padding.
+    /// The [`MediaSegment`]s are completely encrypted using the Advanced
+    /// Encryption Standard ([AES-128]) with a 128-bit key, Cipher Block
+    /// Chaining (CBC), and [Public-Key Cryptography Standards #7 (PKCS7)]
+    /// padding.
     ///
     /// CBC is restarted on each segment boundary, using either the
-    /// Initialization Vector (IV) attribute value or the Media Sequence
-    /// Number as the IV.
+    /// Initialization Vector (IV) or the Media Sequence Number as the IV
+    ///
+    /// ```
+    /// # let media_sequence_number = 5;
+    /// # assert_eq!(
+    /// format!("0x{:032x}", media_sequence_number)
+    /// # , "00000000000000000000000000000005".to_string());
+    /// ```
     ///
     /// [`MediaSegment`]: crate::MediaSegment
     /// [AES-128]: http://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.197.pdf
     /// [Public-Key Cryptography Standards #7 (PKCS7)]: https://tools.ietf.org/html/rfc5652
     #[strum(serialize = "AES-128")]
     Aes128,
-    /// `SampleAes` means that the [`MediaSegment`]s
-    /// contain media samples, such as audio or video, that are encrypted
-    /// using the Advanced Encryption Standard ([`AES-128`]). How these media
-    /// streams are encrypted and encapsulated in a segment depends on the
-    /// media encoding and the media format of the segment. fMP4 Media
-    /// Segments are encrypted using the 'cbcs' scheme of
-    /// [Common Encryption].  Encryption of other Media Segment
-    /// formats containing [H.264], [AAC], [AC-3],
-    /// and Enhanced [AC-3] media streams is described in the HTTP
-    /// Live Streaming (HLS) [SampleEncryption specification].
+    /// The [`MediaSegment`]s contain media samples, such as audio or video,
+    /// that are encrypted using the Advanced Encryption Standard ([`AES-128`]).
+    ///
+    /// How these media streams are encrypted and encapsulated in a segment
+    /// depends on the media encoding and the media format of the segment.
+    ///
+    /// `fMP4` [`MediaSegment`]s are encrypted using the `cbcs` scheme of
+    /// [Common Encryption].
+    /// Encryption of other [`MediaSegment`] formats containing [H.264], [AAC],
+    /// [AC-3], and Enhanced [AC-3] media streams is described in the
+    /// [HTTP Live Streaming (HLS) SampleEncryption specification].
     ///
     /// [`MediaSegment`]: crate::MediaSegment
     /// [`AES-128`]: http://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.197.pdf
@@ -45,7 +48,8 @@ pub enum EncryptionMethod {
     /// [H.264]: https://tools.ietf.org/html/rfc8216#ref-H_264
     /// [AAC]: https://tools.ietf.org/html/rfc8216#ref-ISO_14496
     /// [AC-3]: https://tools.ietf.org/html/rfc8216#ref-AC_3
-    /// [SampleEncryption specification]: https://tools.ietf.org/html/rfc8216#ref-SampleEnc
+    /// [HTTP Live Streaming (HLS) SampleEncryption specification]:
+    /// https://tools.ietf.org/html/rfc8216#ref-SampleEnc
     SampleAes,
 }