From 4ffd4350f864d697a72fcc367d4d833656ed668c Mon Sep 17 00:00:00 2001 From: Luro02 <24826124+Luro02@users.noreply.github.com> Date: Sat, 5 Oct 2019 14:45:40 +0200 Subject: [PATCH] improve documentation #31 --- src/master_playlist.rs | 34 ++++++++++++++++++++++++++++++++++ src/tags/media_segment/key.rs | 32 ++++++++++++++++---------------- src/tags/shared/start.rs | 2 +- src/types/decryption_key.rs | 14 +++++++------- 4 files changed, 58 insertions(+), 24 deletions(-) diff --git a/src/master_playlist.rs b/src/master_playlist.rs index 7ba57bc..e4ea9e4 100644 --- a/src/master_playlist.rs +++ b/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, #[builder(default)] /// Sets the [`ExtXStart`] tag. + /// + /// # Note + /// This tag is optional. start_tag: Option, #[builder(default)] /// Sets the [`ExtXMedia`] tag. + /// + /// # Note + /// This tag is optional. media_tags: Vec, #[builder(default)] /// Sets all [`ExtXStreamInf`] tags. + /// + /// # Note + /// This tag is optional. stream_inf_tags: Vec, #[builder(default)] /// Sets all [`ExtXIFrameStreamInf`] tags. + /// + /// # Note + /// This tag is optional. i_frame_stream_inf_tags: Vec, #[builder(default)] /// Sets all [`ExtXSessionData`] tags. + /// + /// # Note + /// This tag is optional. session_data_tags: Vec, #[builder(default)] /// Sets all [`ExtXSessionKey`] tags. + /// + /// # Note + /// This tag is optional. session_key_tags: Vec, } 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. diff --git a/src/tags/media_segment/key.rs b/src/tags/media_segment/key.rs index df15ef2..b5e0528 100644 --- a/src/tags/media_segment/key.rs +++ b/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: -/// ``` -/// /// # 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; diff --git a/src/tags/shared/start.rs b/src/tags/shared/start.rs index 54d897a..701b792 100644 --- a/src/tags/shared/start.rs +++ b/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 { diff --git a/src/types/decryption_key.rs b/src/types/decryption_key.rs index 9476d2a..0d17686 100644 --- a/src/types/decryption_key.rs +++ b/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 { 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 /// ```