From 17b5456aca7fcd4193f42c12179c167ffe9cc3ce Mon Sep 17 00:00:00 2001 From: Alison Watson Date: Tue, 18 Jun 2019 01:40:39 -0400 Subject: [PATCH] maraiah: more documentation --- README.md | 8 +----- source/cenum.rs | 12 ++++---- source/doc.rs | 22 +++++++++++++++ source/ffi.rs | 30 ++++++++++++++++++-- source/lib.rs | 20 +++++++++++++- source/meta.rs | 55 ++++++++++++++++++++++++++----------- source/tycho/source/meta.rs | 10 +++---- 7 files changed, 119 insertions(+), 38 deletions(-) create mode 100644 source/doc.rs diff --git a/README.md b/README.md index 18a3209..8810337 100644 --- a/README.md +++ b/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` diff --git a/source/cenum.rs b/source/cenum.rs index dc728e1..4ee5867 100644 --- a/source/cenum.rs +++ b/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)] diff --git a/source/doc.rs b/source/doc.rs new file mode 100644 index 0000000..e18b78b --- /dev/null +++ b/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 diff --git a/source/ffi.rs b/source/ffi.rs index 97e2edc..ccab8e9 100644 --- a/source/ffi.rs +++ b/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()} diff --git a/source/lib.rs b/source/lib.rs index 8df2565..3884400 100644 --- a/source/lib.rs +++ b/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; diff --git a/source/meta.rs b/source/meta.rs index 65fe96f..c0cabfd 100644 --- a/source/meta.rs +++ b/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 diff --git a/source/tycho/source/meta.rs b/source/tycho/source/meta.rs index 06e2c3e..3dfa9f8 100644 --- a/source/tycho/source/meta.rs +++ b/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