rustdoc stuff

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "vcfexpr"
-version = "0.1.0"
+version = "0.2.0"
 edition = "2021"
 
 # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
@@ -12,6 +12,7 @@ clap = { version = "4.5.4", features = ["derive"] }
 env_logger = "0.11.3"
 log = "0.4.21"
 parking_lot = { version = "0.12.1", features = ["arc_lock"] }
+#libc = "0.2.153"
 
 [[bin]]
 name = "vcfexpr"
@@ -20,3 +21,8 @@ src = "src/main.rs"
 [lib]
 name = "vcfexpr"
 src = "src/lib.rs"
+
+
+[profile.release]
+lto = "fat"
+codegen-units = 1

src/lib.rs

@@ -1,3 +1,5 @@
+//! This crate supports applying user-defined lua expressions to each variant in a VCF File.
+//!
 pub mod genotypes;
 //pub mod sample;
 pub mod header;

src/vcfexpr.rs

@@ -8,6 +8,7 @@ use std::{collections::HashMap, hash::Hash, io::Write};
 
 use crate::variant::Variant;
 
+/// VCFExpr is the only entry-point for this library.
 pub struct VCFExpr<'lua> {
     lua: &'lua Lua,
     vcf_reader: Option<bcf::Reader>,
@@ -20,12 +21,15 @@ pub struct VCFExpr<'lua> {
     variants_passing: usize,
 }
 
+/// This allows `evaluate` to return either a string, a VCF record, or nothing.
 pub enum StringOrVariant {
     String(String),
     Variant(Option<bcf::Record>),
     None,
 }
 
+/// `EitherWriter` encapsulates the different types of writers we can use.
+/// `File` and `Stdout` are for template output and `Vcf` is for VCF records.
 pub enum EitherWriter {
     Vcf(bcf::Writer),
     File(std::io::BufWriter<std::fs::File>),
@@ -120,6 +124,9 @@ impl<'lua> VCFExpr<'lua> {
     /// The expressions should return a boolean. Evaluations will stop on the first true expression.
     /// If a template is provided, the template will be evaluated in the same scope as the expression and used
     /// to generate the text output. If no template is provided, the VCF record will be written to the output.
+    /// The template is a [luau string template].
+    ///
+    /// [luau string template]: https://luau-lang.org/syntax#string-interpolation
     pub fn new(
         lua: &'lua Lua,
         vcf_path: String,
@@ -246,11 +253,14 @@ impl<'lua> VCFExpr<'lua> {
         Ok(())
     }
 
-    /// Return a reference to the bcf::Reader object.
+    /// Take ownership of the the bcf::Reader object.
+    /// This must be called before using `evaluate`
     pub fn reader(&mut self) -> bcf::Reader {
         self.vcf_reader.take().expect("reader already taken")
     }
 
+    /// Take ownership of the the Writer enum.
+    /// This must be called before using `evaluate`
     pub fn writer(&mut self) -> EitherWriter {
         self.writer.take().expect("writer already taken")
     }
@@ -287,6 +297,7 @@ impl<'lua> VCFExpr<'lua> {
         Ok(())
     }
 
+    /// Evaluate the expressions and optional template for a single record.
     pub fn evaluate(&mut self, record: bcf::Record) -> std::io::Result<StringOrVariant> {
         let mut variant = Variant::new(record);
         self.variants_evaluated += 1;