improve documentation #31

src/master_playlist.rs

@@ -21,29 +21,63 @@ pub struct MasterPlaylist {
     version_tag: ExtXVersion,
     #[builder(default)]
     /// Sets the [`ExtXIndependentSegments`] tag.
+    ///
+    /// # Note
+    /// This tag is optional.
     independent_segments_tag: Option<ExtXIndependentSegments>,
     #[builder(default)]
     /// Sets the [`ExtXStart`] tag.
+    ///
+    /// # Note
+    /// This tag is optional.
     start_tag: Option<ExtXStart>,
     #[builder(default)]
     /// Sets the [`ExtXMedia`] tag.
+    ///
+    /// # Note
+    /// This tag is optional.
     media_tags: Vec<ExtXMedia>,
     #[builder(default)]
     /// Sets all [`ExtXStreamInf`] tags.
+    ///
+    /// # Note
+    /// This tag is optional.
     stream_inf_tags: Vec<ExtXStreamInf>,
     #[builder(default)]
     /// Sets all [`ExtXIFrameStreamInf`] tags.
+    ///
+    /// # Note
+    /// This tag is optional.
     i_frame_stream_inf_tags: Vec<ExtXIFrameStreamInf>,
     #[builder(default)]
     /// Sets all [`ExtXSessionData`] tags.
+    ///
+    /// # Note
+    /// This tag is optional.
     session_data_tags: Vec<ExtXSessionData>,
     #[builder(default)]
     /// Sets all [`ExtXSessionKey`] tags.
+    ///
+    /// # Note
+    /// This tag is optional.
     session_key_tags: Vec<ExtXSessionKey>,
 }
 
 impl MasterPlaylist {
     /// Returns a Builder for a [`MasterPlaylist`].
+    ///
+    /// # Example
+    /// ```
+    /// use hls_m3u8::tags::ExtXStart;
+    /// use hls_m3u8::MasterPlaylist;
+    ///
+    /// # fn main() -> Result<(), hls_m3u8::Error> {
+    /// MasterPlaylist::builder()
+    ///     .start_tag(ExtXStart::new(20.123456))
+    ///     .build()?;
+    /// # Ok(())
+    /// # }
+    /// ```
     pub fn builder() -> MasterPlaylistBuilder { MasterPlaylistBuilder::default() }
 
     /// Returns the [`ExtXIndependentSegments`] tag contained in the playlist.

src/tags/media_segment/key.rs

@@ -2,31 +2,26 @@ use std::fmt;
 use std::ops::{Deref, DerefMut};
 use std::str::FromStr;
 
-use crate::types::{DecryptionKey, EncryptionMethod};
+use crate::types::{DecryptionKey, EncryptionMethod, ProtocolVersion};
 use crate::utils::tag;
-use crate::Error;
+use crate::{Error, RequiredVersion};
 
-/// # [4.4.2.4. EXT-X-KEY]
+/// # [4.3.2.4. EXT-X-KEY]
+///
 /// [`Media Segment`]s may be encrypted. The [`ExtXKey`] tag specifies how to
 /// decrypt them. It applies to every [`Media Segment`] and to every Media
 /// Initialization Section declared by an [`ExtXMap`] tag, that appears
 /// between it and the next [`ExtXKey`] tag in the Playlist file with the
 /// same [`KeyFormat`] attribute (or the end of the Playlist file).
 ///
-/// The format is:
-/// ```text
-/// #EXT-X-KEY:<attribute-list>
-/// ```
-///
 /// # Note
-/// In case of an empty key (`EncryptionMethod::None`),
+/// In case of an empty key ([`EncryptionMethod::None`]),
 /// all attributes will be ignored.
 ///
 /// [`KeyFormat`]: crate::types::KeyFormat
 /// [`ExtXMap`]: crate::tags::ExtXMap
 /// [`Media Segment`]: crate::MediaSegment
-/// [4.4.2.4. EXT-X-KEY]:
-/// https://tools.ietf.org/html/draft-pantos-hls-rfc8216bis-04#section-4.4.2.4
+/// [4.3.2.4. EXT-X-KEY]: https://tools.ietf.org/html/rfc8216#section-4.3.2.4
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub struct ExtXKey(DecryptionKey);
 
@@ -37,7 +32,7 @@ impl ExtXKey {
     ///
     /// # Example
     /// ```
-    /// use hls_m3u8::tags::ExtXKey;
+    /// # use hls_m3u8::tags::ExtXKey;
     /// use hls_m3u8::types::EncryptionMethod;
     ///
     /// let key = ExtXKey::new(EncryptionMethod::Aes128, "https://www.example.com/");
@@ -55,8 +50,7 @@ impl ExtXKey {
     ///
     /// # Example
     /// ```
-    /// use hls_m3u8::tags::ExtXKey;
-    ///
+    /// # use hls_m3u8::tags::ExtXKey;
     /// let key = ExtXKey::empty();
     ///
     /// assert_eq!(key.to_string(), "#EXT-X-KEY:METHOD=NONE");
@@ -72,20 +66,26 @@ impl ExtXKey {
     }
 
     /// Returns whether the [`EncryptionMethod`] is
-    /// [`None`](EncryptionMethod::None).
+    /// [`None`].
     ///
     /// # Example
     /// ```
-    /// use hls_m3u8::tags::ExtXKey;
+    /// # use hls_m3u8::tags::ExtXKey;
     /// use hls_m3u8::types::EncryptionMethod;
     ///
     /// let key = ExtXKey::empty();
     ///
     /// assert_eq!(key.method() == EncryptionMethod::None, key.is_empty());
     /// ```
+    ///
+    /// [`None`]: EncryptionMethod::None
     pub fn is_empty(&self) -> bool { self.0.method() == EncryptionMethod::None }
 }
 
+impl RequiredVersion for ExtXKey {
+    fn required_version(&self) -> ProtocolVersion { self.0.required_version() }
+}
+
 impl FromStr for ExtXKey {
     type Err = Error;
 

src/tags/shared/start.rs

@@ -26,7 +26,7 @@ impl ExtXStart {
     /// # Example
     /// ```
     /// # use hls_m3u8::tags::ExtXStart;
-    /// ExtXStart::new(20.123456);
+    /// let start = ExtXStart::new(20.123456);
     /// ```
     pub fn new(time_offset: f64) -> Self {
         Self {

src/types/decryption_key.rs

@@ -45,7 +45,7 @@ impl DecryptionKeyBuilder {
 }
 
 impl DecryptionKey {
-    /// Makes a new [DecryptionKey].
+    /// Makes a new [`DecryptionKey`].
     ///
     /// # Example
     /// ```
@@ -64,7 +64,7 @@ impl DecryptionKey {
         }
     }
 
-    /// Returns the [EncryptionMethod].
+    /// Returns the [`EncryptionMethod`].
     ///
     /// # Example
     /// ```
@@ -80,7 +80,7 @@ impl DecryptionKey {
     /// Returns a Builder to build a [DecryptionKey].
     pub fn builder() -> DecryptionKeyBuilder { DecryptionKeyBuilder::default() }
 
-    /// Sets the [EncryptionMethod].
+    /// Sets the [`EncryptionMethod`].
     ///
     /// # Example
     /// ```
@@ -120,7 +120,7 @@ impl DecryptionKey {
     /// Sets the `URI` attribute.
     ///
     /// # Note
-    /// This attribute is required, if the [EncryptionMethod] is not `None`.
+    /// This attribute is required, if the [`EncryptionMethod`] is not `None`.
     ///
     /// # Example
     /// ```
@@ -207,7 +207,7 @@ impl DecryptionKey {
     /// ```
     pub const fn key_format(&self) -> Option<KeyFormat> { self.key_format }
 
-    /// Sets the [KeyFormat] attribute.
+    /// Sets the [`KeyFormat`] attribute.
     ///
     /// # Example
     /// ```
@@ -225,7 +225,7 @@ impl DecryptionKey {
         self
     }
 
-    /// Returns the [KeyFormatVersions] attribute.
+    /// Returns the [`KeyFormatVersions`] attribute.
     ///
     /// # Example
     /// ```
@@ -245,7 +245,7 @@ impl DecryptionKey {
         &self.key_format_versions
     }
 
-    /// Sets the [KeyFormatVersions] attribute.
+    /// Sets the [`KeyFormatVersions`] attribute.
     ///
     /// # Example
     /// ```