From: Kostya Shishkov <kostya.shishkov@gmail.com>
Date: Tue, 18 Feb 2020 15:06:36 +0000 (+0100)
Subject: core/test: document module
X-Git-Url: https://git.nihav.org/?a=commitdiff_plain;h=fb8e31774f738353e3ada384a0751cea63936c15;p=nihav.git

core/test: document module
---

diff --git a/nihav-core/src/test/dec_video.rs b/nihav-core/src/test/dec_video.rs
index 9c219a0..1dc2bed 100644
--- a/nihav-core/src/test/dec_video.rs
+++ b/nihav-core/src/test/dec_video.rs
@@ -1,3 +1,4 @@
+//! Routines for testing decoders.
 use std::fs::File;
 use std::io::prelude::*;
 use crate::frame::*;
@@ -197,6 +198,17 @@ fn write_ppm(pfx: &str, strno: usize, num: u64, frm: NAFrameRef) {
     WavWriter::new(&mut wr)
 }*/
 
+/// Tests decoding of provided file and optionally outputs video frames as PNM (PPM for RGB video, PGM for YUV).
+///
+/// This function expects the following arguments:
+/// * `demuxer` - container format name (used to find proper demuxer for it)
+/// * `name` - input file name
+/// * `limit` - optional PTS value after which decoding is stopped
+/// * `decode_video`/`decode_audio` - flags for enabling video/audio decoding
+/// * `video_pfx` - prefix for video frames written as pictures (if enabled then output picture names should look like `<crate_name>/assets/test_out/PFXout00_000000.ppm`
+/// * `dmx_reg` and `dec_reg` - registered demuxers and decoders that should contain demuxer and decoder(s) needed to decode the provided file.
+///
+/// Since the function is intended for tests, it will panic instead of returning an error.
 pub fn test_file_decoding(demuxer: &str, name: &str, limit: Option<u64>,
                           decode_video: bool, decode_audio: bool,
                           video_pfx: Option<&str>,
@@ -257,6 +269,13 @@ panic!(" unknown format");
     }
 }
 
+/// Tests audio decoder with the content in the provided file and optionally outputs decoded audio.
+///
+/// The syntax is very similar to [`test_file_decoding`] except that it is intended for testing audio codecs.
+///
+/// Since the function is intended for tests, it will panic instead of returning an error.
+///
+/// [`test_file_decoding`]: ./fn.test_file_decoding.html
 pub fn test_decode_audio(demuxer: &str, name: &str, limit: Option<u64>, audio_pfx: Option<&str>,
                          dmx_reg: &RegisteredDemuxers, dec_reg: &RegisteredDecoders) {
     let dmx_f = dmx_reg.find_demuxer(demuxer).unwrap();
@@ -406,6 +425,26 @@ fn frame_checksum(md5: &mut MD5, frm: NAFrameRef) {
     };
 }
 
+/// Tests decoder for requested codec in provided file.
+///
+/// This functions tries to decode a stream corresponding to `dec_name` codec in input file and validate the results against expected ones.
+///
+/// Since the function is intended for tests, it will panic instead of returning an error.
+///
+/// # Examples
+///
+/// Test RealVideo 4 decoder in test stream:
+/// ```no_run
+/// use nihav_core::test::ExpectedTestResult;
+/// use nihav_core::test::dec_video::test_decoding;
+/// use nihav_core::codecs::RegisteredDecoders;
+/// use nihav_core::demuxers::RegisteredDemuxers;
+///
+/// let mut dmx_reg = RegisteredDemuxers::new();
+/// let mut dec_reg = RegisteredDecoders::new();
+/// // ... register RealMedia demuxers and RealVideo decoders ...
+/// test_decoding("realmedia", "rv40", "assets/test_file.rmvb", None, &dmx_reg, &dec_reg, ExpectedTestResult::MD5([0x00010203, 0x04050607, 0x08090a0b, 0x0c0d0e0f]));
+/// ```
 pub fn test_decoding(demuxer: &str, dec_name: &str, filename: &str, limit: Option<u64>,
                      dmx_reg: &RegisteredDemuxers, dec_reg: &RegisteredDecoders,
                      test: ExpectedTestResult) {
diff --git a/nihav-core/src/test/mod.rs b/nihav-core/src/test/mod.rs
index 15f13eb..367be24 100644
--- a/nihav-core/src/test/mod.rs
+++ b/nihav-core/src/test/mod.rs
@@ -1,11 +1,21 @@
+//! Decoder testing functionality.
+//!
+//! This module provides functions that may be used in internal test to check that decoders produce output and that they produce expected output.
 pub mod dec_video;
 pub mod wavwriter;
 
 mod md5; // for internal checksums only
 
+/// Decoder testing modes.
+///
+/// NihAV has its own MD5 hasher that calculates hash for input frame in a deterministic way (i.e. no endianness issues) and it outputs hash as `[u32; 4]`. During testing the resulting hash will be printed out so when the test fails you can find what was the calculated hash (and use it as a reference if you are implementing a new test).
 pub enum ExpectedTestResult {
+    /// Decoding runs without errors.
     Decodes,
+    /// Full decoded output is expected to be equal to this MD5 hash.
     MD5([u32; 4]),
+    /// Each decoded frame hash should be equal to the corresponding MD5 hash.
     MD5Frames(Vec<[u32; 4]>),
+    /// Test function should report decoded frame hashes to be used as the reference later.
     GenerateMD5Frames,
 }
diff --git a/nihav-core/src/test/wavwriter.rs b/nihav-core/src/test/wavwriter.rs
index 0c32430..50b1949 100644
--- a/nihav-core/src/test/wavwriter.rs
+++ b/nihav-core/src/test/wavwriter.rs
@@ -1,7 +1,9 @@
+//! Audio output in WAV format.
 use crate::io::byteio::*;
 use crate::frame::*;
 use std::io::SeekFrom;
 
+/// WAVE output writer.
 pub struct WavWriter<'a> {
     io: &'a mut ByteWriter<'a>,
     data_pos: u64,
@@ -46,9 +48,13 @@ macro_rules! write_data {
 }
 
 impl<'a> WavWriter<'a> {
+    /// Constructs a new `WavWriter` instance.
     pub fn new(io: &'a mut ByteWriter<'a>) -> Self {
         WavWriter { io, data_pos: 0 }
     }
+    /// Writes audio format information to the file header.
+    ///
+    /// This function should be called exactly once before writing actual audio data.
     pub fn write_header(&mut self, ainfo: NAAudioInfo) -> ByteIOResult<()> {
         let bits = ainfo.get_format().get_bits() as usize;
 
@@ -78,6 +84,7 @@ impl<'a> WavWriter<'a> {
         self.data_pos = self.io.tell();
         Ok(())
     }
+    /// Writes audio data.
     pub fn write_frame(&mut self, abuf: NABufferType) -> ByteIOResult<()> {
         match abuf {
             NABufferType::AudioU8(ref buf) => {