maraiah: make checkdata not a macro

README.md

@@ -9,13 +9,7 @@ is derived from the Japanese transliteration of "Mariah," and is pronounced
 The basis of this project is the Rust project `maraiah` which provides functions
 and structures to build applications which work with Marathon's data.
 
-Maraiah comes with a set of almost fully portable tools written in Rust,
-including binary file reading, safe C-like `enum` reading, improved error
-handling, FFI tools, fixed point numbers, and image and sound structures.
-
-Maraiah also comes with APIs for working with various data formats, primarily
-Marathon's. It also handles Macintosh PICT files, Portable PixMap, TARGA, RIFF
-WAVE, and more.
+See [the crate documentation](source/lib.rs) for more information.
 
 ## `maraiah-leela`
 

source/bin.rs

@@ -160,6 +160,9 @@ macro_rules! rd_impl {
 /// ```
 /// # #[macro_use] extern crate maraiah;
 /// # use maraiah::err::*;
+/// #
+/// # fn main() -> ResultS<()>
+/// # {
 /// let buffer = &[4, 0, 2, 0, 0, 0, 6];
 ///
 /// read_data! {
@@ -176,6 +179,7 @@ macro_rules! rd_impl {
 /// assert_eq!(six, 6_u8);
 /// assert_eq!(byte, &[2, 0, 0, 0]);
 /// # Ok(())
+/// # }
 /// ```
 #[macro_export]
 macro_rules! read_data {
@@ -185,20 +189,24 @@ macro_rules! read_data {
            $($ex:ident$(::$exc:ident)*)*;)*
       }
    ) => {
-      $crate::check_data!($at + $sz, $b);
+      $crate::bin::check_data($b, $at + $sz)?;
       $($crate::rd_impl!($e, $b, $at, $n;
                          $($rn;)? $nam, $($ex$(::$exc)*,)* $t$(::$tc)*);)*
    };
 }
 
 /// Checks if there is enough data in `b`.
-#[macro_export]
-macro_rules! check_data {
-   ($sz:expr, $b:expr) => {
-      if $b.len() < $sz {
-         return Err(err_msg("not enough data"));
-      }
-   };
+///
+/// # Errors
+///
+/// Returns `Err` if `b.len()` is less than `sz`.
+pub fn check_data(b: &[u8], sz: usize) -> ResultS<()>
+{
+   if b.len() < sz {
+      Err(err_msg("not enough data"))
+   } else {
+      Ok(())
+   }
 }
 
 /// Casts a `u32` to a `usize`.
@@ -417,7 +425,7 @@ pub fn rd_ofstable<T, F>(b: &[u8],
 
    for _ in 0..num {
       let ofs = usize_from_u32(u32b(&b[p..p + 4]));
-      check_data!(ofs, b);
+      check_data(b, ofs)?;
       v.push(read(&b[ofs..])?);
       p += 4;
    }

source/cenum.rs

@@ -1,10 +1,10 @@
 #![doc(hidden)]
 
-/// Creates an enumeration and function for converting a representation into
-/// the enumeration type.
+/// Creates an enumeration and function for converting a representation into the
+/// enumeration type.
 ///
-/// The syntax is similar to the `bitflags` macro, but each value has the
-/// syntax `value => enumeration`. `enum` is used instead of `struct`.
+/// The syntax is similar to the `bitflags` macro, but each value has the syntax
+/// `value = enumeration`. `enum` is used instead of `struct`.
 ///
 /// This will generate an `enum $t` as well as implement `TryFrom` on it which
 /// will return `Result<$t, ReprError>`.
@@ -39,7 +39,7 @@ macro_rules! c_enum
       $(#[$outer:meta])*
       $vi:vis enum $t:ident: $ti:ident
       {
-         $($en:ident = $va:expr),+ $(,)?
+         $($(#[$vouter:meta])* $en:ident = $va:expr),+ $(,)?
       }
    ) => {
       $(#[$outer])*
@@ -47,7 +47,7 @@ macro_rules! c_enum
       #[repr($ti)]
       $vi enum $t
       {
-         $($en = $va,)+
+         $($(#[$vouter])* $en = $va,)+
       }
 
       #[allow(unused_qualifications)]

source/defl.rs

@@ -1,6 +1,6 @@
 //! DEFLATE loader.
 
-use crate::{bit::*, err::*};
+use crate::{bin::check_data, bit::*, err::*};
 use std::cmp::Ordering;
 
 /// Loads a ZLIB file header.
@@ -76,7 +76,7 @@ pub fn load_gzip_header(b: &[u8]) -> ResultS<usize>
 
       p += 2 + xlen;
 
-      check_data!(p, b);
+      check_data(b, p)?;
    }
 
    if fl & FNAME != 0 {
@@ -90,7 +90,7 @@ pub fn load_gzip_header(b: &[u8]) -> ResultS<usize>
    if fl & FHCRC != 0 {
       p += 2;
 
-      check_data!(p, b);
+      check_data(b, p)?;
    }
 
    Ok(p)

source/doc.rs

@@ -0,0 +1,22 @@
+#![doc(hidden)]
+
+/// Macro-izes `#[doc = x]`.
+///
+/// # Examples
+///
+/// ```
+/// use maraiah::doc_comment;
+///
+/// doc_comment! {
+///    concat!("Have a nice", " day", "!"),
+///    const A: u32 = 5;
+/// }
+///
+/// assert_eq!(A, 5);
+/// ```
+#[macro_export]
+macro_rules! doc_comment {
+   ($x:expr, $($tt:tt)*) => {#[doc = $x] $($tt)*}
+}
+
+// EOF

source/ffi.rs

@@ -1,11 +1,27 @@
 //! Foreign function interface utilities.
 
 use crate::err::*;
-pub use std::{ffi::*,
-              os::raw::*,
-              ptr::{null, null_mut}};
+
+pub use std::{ffi::*, os::raw::*, ptr::{null, null_mut}};
 
 /// Creates a C string from a literal.
+///
+/// This is done by concatenating a null byte with the string and converting it
+/// to a pointer.
+///
+/// # Examples
+///
+/// ```
+/// use maraiah::c_str;
+///
+/// let st = c_str!("test");
+///
+/// assert!(!st.is_null());
+///
+/// unsafe {
+///    assert_eq!(std::slice::from_raw_parts(st, 5), &[116, 101, 115, 116, 0]);
+/// }
+/// ```
 #[macro_export]
 macro_rules! c_str {
    ($s:expr) => {
@@ -13,9 +29,17 @@ macro_rules! c_str {
    };
 }
 
+/// Returns [`null`] as a [`*const c_void`].
+///
+/// [`null`]: fn.null.html
+/// [`*const c_void`]: enum.c_void.html
 #[inline]
 pub const fn null_void() -> *const c_void {null()}
 
+/// Returns [`null_mut`] as a [`*mut c_void`].
+///
+/// [`null_mut`]: fn.null_mut.html
+/// [`*mut c_void`]: enum.c_void.html
 #[inline]
 pub const fn null_mut_void() -> *mut c_void {null_mut()}
 

source/lib.rs

@@ -1,3 +1,19 @@
+//! This is the base library for the Maraiah tool set. This library contains
+//! functions and structures for reading many file formats, primarily those used
+//! by Marathon, Marathon 2, and Marathon Infinity.
+//!
+//! Maraiah comes with a set of almost fully portable tools written in Rust,
+//! including binary file reading, safe C-like `enum` reading, improved error
+//! handling, FFI tools, fixed point numbers, and image and sound structures.
+//!
+//! Maraiah also comes with APIs for working with various data formats,
+//! primarily Marathon's. It also handles Macintosh PICT files, Portable PixMap,
+//! TARGA, RIFF WAVE, and more.
+//!
+//! # Features
+//!
+//! Maraiah supports serializing and deserializing through `serde` with the
+//! `serde_obj` feature.
 #![deny(anonymous_parameters)]
 #![deny(bare_trait_objects)]
 #![deny(elided_lifetimes_in_paths)]
@@ -47,12 +63,14 @@
 #![deny(clippy::use_self)]
 #![deny(clippy::used_underscore_binding)]
 
+#[macro_use]
+mod doc;
 #[macro_use]
 pub mod ffi;
 #[macro_use]
 pub mod err;
 #[macro_use]
-pub mod cenum;
+mod cenum;
 #[macro_use]
 pub mod bin;
 

source/map/iidx.rs

@@ -1,11 +1,11 @@
 //! `iidx` chunk.
 
-use crate::{bin::u16b, err::*};
+use crate::{bin::{check_data, u16b}, err::*};
 
 /// Reads an `iidx` chunk.
 pub fn read(b: &[u8]) -> ResultS<(u16, usize)>
 {
-   check_data!(2, b);
+   check_data(b, 2)?;
 
    Ok((u16b(b), 2))
 }

source/meta.rs

@@ -1,28 +1,51 @@
 //! Meta-information of this crate.
 
-use crate::ffi;
-
 macro_rules! meta_str {
-   ($($name:ident = $cname:ident = $e:expr;)*) => {
+   ($($(#[$outer:meta])* $name:ident = $cname:ident = $e:expr;)*) => {
       $(
-      pub const $name:  &'static str = $e;
-      pub const $cname: ffi::NT = c_str!($e);
+      $(#[$outer])* pub const $name:  &'static str = $e;
       )*
+      pub mod ffi
+      {
+         $(
+         doc_comment! {
+            concat!("FFI variant of [`",
+                    stringify!($name),
+                    "`]\n\n[`",
+                    stringify!($name),
+                    "`]: ../constant.",
+                    stringify!($name),
+                    ".html"),
+            pub const $cname: crate::ffi::NT = c_str!($e);
+         }
+         )*
+      }
    }
 }
 
 meta_str!(
-   AUTHORS       = C_AUTHORS        = env!("CARGO_PKG_AUTHORS");
-   DESCRIPTION   = C_DESCRIPTION    = env!("CARGO_PKG_DESCRIPTION");
-   HOMEPAGE      = C_HOMEPAGE       = env!("CARGO_PKG_HOMEPAGE");
-   LICENSE_TEXT  = C_LICENSE_TEXT   = include_str!("../LICENSE");
-   NAME          = C_NAME           = env!("CARGO_PKG_NAME");
-   REPOSITORY    = C_REPOSITORY     = env!("CARGO_PKG_REPOSITORY");
-   VERSION       = C_VERSION        = env!("CARGO_PKG_VERSION");
-   VERSION_MAJOR = C_VERSION_MAJOR  = env!("CARGO_PKG_VERSION_MAJOR");
-   VERSION_MINOR = C_VERSION_MINOR  = env!("CARGO_PKG_VERSION_MINOR");
-   VERSION_PATCH = C_VERSION_PATCH  = env!("CARGO_PKG_VERSION_PATCH");
-   VERSION_PRE   = C_VERSION_PRE    = env!("CARGO_PKG_VERSION_PRE");
+   /// The authors of this crate, `:` separated.
+   AUTHORS       = AUTHORS_C        = env!("CARGO_PKG_AUTHORS");
+   /// The description of this crate.
+   DESCRIPTION   = DESCRIPTION_C    = env!("CARGO_PKG_DESCRIPTION");
+   /// The home page of this crate.
+   HOMEPAGE      = HOMEPAGE_C       = env!("CARGO_PKG_HOMEPAGE");
+   /// The full license text of this crate.
+   LICENSE_TEXT  = LICENSE_TEXT_C   = include_str!("../LICENSE");
+   /// The name of this crate.
+   NAME          = NAME_C           = env!("CARGO_PKG_NAME");
+   /// The repository of this crate.
+   REPOSITORY    = REPOSITORY_C     = env!("CARGO_PKG_REPOSITORY");
+   /// The full version of this crate.
+   VERSION       = VERSION_C        = env!("CARGO_PKG_VERSION");
+   /// The major version of this crate.
+   VERSION_MAJOR = VERSION_MAJOR_C  = env!("CARGO_PKG_VERSION_MAJOR");
+   /// The minor version of this crate.
+   VERSION_MINOR = VERSION_MINOR_C  = env!("CARGO_PKG_VERSION_MINOR");
+   /// The patch version of this crate.
+   VERSION_PATCH = VERSION_PATCH_C  = env!("CARGO_PKG_VERSION_PATCH");
+   /// The pre-release version of this crate.
+   VERSION_PRE   = VERSION_PRE_C    = env!("CARGO_PKG_VERSION_PRE");
 );
 
 // EOF

source/tycho/bindings.json

@@ -2,8 +2,8 @@
    "cppFile": "",
    "rust": {
       "dir": "",
-      "interfaceModule": "qintr",
-      "implementationModule": "qimpl"
+      "interfaceModule": "ffi",
+      "implementationModule": "gui"
    },
    "objects": {
       "MapModel": {

source/tycho/cc_source/project.cc

@@ -21,7 +21,7 @@ ProjectModel::ProjectModel(ProjectModel &&o) :
 ProjectModel::~ProjectModel()
 {
    switch(modelType) {
-      case Map: delete modelMap;
+      case Map: delete modelMap; break;
    }
 }
 

source/tycho/source/gui.rs

@@ -0,0 +1,8 @@
+//! GUI implementation.
+
+mod ffi;
+mod map;
+
+pub use self::map::MapModel;
+
+// EOF

source/tycho/source/gui/ffi.rs

@@ -4,6 +4,6 @@
 
 use maraiah::ffi as libc;
 
-include!(concat!(env!("OUT_DIR"), "/src/qintr.rs"));
+include!(concat!(env!("OUT_DIR"), "/src/ffi.rs"));
 
 // EOF

source/tycho/source/gui/map.rs

@@ -1,6 +1,6 @@
 //! Map model.
 
-use crate::qintr::*;
+use super::ffi::*;
 //use memmap::Mmap;
 use maraiah::map;
 

source/tycho/source/main.rs

@@ -1,8 +1,7 @@
 use maraiah::{err::*, ffi};
 
+mod gui;
 mod meta;
-mod qimpl;
-mod qintr;
 
 extern "C" {
    fn main_cc(app_name: *mut ffi::c_char);

source/tycho/source/meta.rs

@@ -15,11 +15,11 @@ macro_rules! meta_str {
 }
 
 meta_str!(
-   tychoAuthors     = meta::C_AUTHORS;
-   tychoHomepage    = meta::C_HOMEPAGE;
-   tychoLicenseText = meta::C_LICENSE_TEXT;
-   tychoRepository  = meta::C_REPOSITORY;
-   tychoVersion     = meta::C_VERSION;
+   tychoAuthors     = meta::ffi::AUTHORS_C;
+   tychoHomepage    = meta::ffi::HOMEPAGE_C;
+   tychoLicenseText = meta::ffi::LICENSE_TEXT_C;
+   tychoRepository  = meta::ffi::REPOSITORY_C;
+   tychoVersion     = meta::ffi::VERSION_C;
 );
 
 // EOF

source/tycho/source/qimpl.rs

@@ -1,7 +0,0 @@
-//! Qt implementation.
-
-mod map;
-
-pub use self::map::*;
-
-// EOF