From: Kostya Shishkov <kostya.shishkov@gmail.com>
Date: Mon, 17 Feb 2020 15:13:18 +0000 (+0100)
Subject: core: document reorder module
X-Git-Url: https://git.nihav.org/?a=commitdiff_plain;h=6c9578bed2944ca6e21aec8d97c8a2e73b24b5fc;p=nihav.git

core: document reorder module
---

diff --git a/nihav-core/src/reorder.rs b/nihav-core/src/reorder.rs
index fe6670c..83896df 100644
--- a/nihav-core/src/reorder.rs
+++ b/nihav-core/src/reorder.rs
@@ -1,18 +1,32 @@
+//! Output frame reordering.
+//!
+//! NihAV decoders output frames in the same order as they are put in.
+//! In result if you want to have frames in display order you might need some frame reorderer.
+//! This module provides such functionality depending on codec type: audio codecs and video codecs without B-frames do not need any reorderer and can use `NoReorderer` if the common interface is required. Codecs with B-frames should use `IPBReorderer`. For codecs with very complex reordering rules like H.264 or H.256 `PictureIDReorderer` will be added eventually.
+//!
+//! You can find out required reorderer by quering codec properties using `nihav_core::register` module.
 use std::mem::swap;
 pub use crate::frame::{FrameType, NAFrameRef};
 
+/// A trait for frame reorderer.
 pub trait FrameReorderer {
+    /// Stores a newly decoded frame.
     fn add_frame(&mut self, fref: NAFrameRef) -> bool;
+    /// Gets the next frame to be displayed (or `None` if that is not possible).
     fn get_frame(&mut self) -> Option<NAFrameRef>;
+    /// Clears all stored frames.
     fn flush(&mut self);
+    /// Retrieves the last frames stored by the reorderer.
     fn get_last_frames(&mut self) -> Option<NAFrameRef>;
 }
 
+/// Zero reorderer.
 pub struct NoReorderer {
     fref:   Option<NAFrameRef>,
 }
 
 impl NoReorderer {
+    /// Constructs a new instance of `NoReorderer`.
     pub fn new() -> Self {
         Self { fref: None }
     }
@@ -36,6 +50,7 @@ impl FrameReorderer for NoReorderer {
     fn get_last_frames(&mut self) -> Option<NAFrameRef> { None }
 }
 
+/// Frame reorderer for codecs with I/P/B frames.
 #[derive(Default)]
 pub struct IPBReorderer {
     rframe:     Option<NAFrameRef>,
@@ -43,6 +58,7 @@ pub struct IPBReorderer {
 }
 
 impl IPBReorderer {
+    /// Constructs a new instance of `IPBReorderer`.
     pub fn new() -> Self { Self::default() }
 }