docu

.vscode/launch.json

@@ -0,0 +1,78 @@
+{
+	// Use IntelliSense to learn about possible attributes.
+	// Hover to view descriptions of existing attributes.
+	// For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
+	"version": "0.2.0",
+	"configurations": [
+		{
+			"type": "lldb",
+			"request": "launch",
+			"name": "Debug unit tests in library 'rga'",
+			"cargo": {
+				"args": ["test", "--no-run", "--lib", "--package=rga"],
+				"filter": {
+					"name": "rga",
+					"kind": "lib"
+				}
+			},
+			"args": [],
+			"cwd": "${workspaceFolder}"
+		},
+		{
+			"type": "lldb",
+			"request": "launch",
+			"name": "Debug executable 'rga'",
+			"cargo": {
+				"args": ["build", "--bin=rga", "--package=rga"],
+				"filter": {
+					"name": "rga",
+					"kind": "bin"
+				}
+			},
+			"args": [],
+			"cwd": "${workspaceFolder}"
+		},
+		{
+			"type": "lldb",
+			"request": "launch",
+			"name": "Debug unit tests in executable 'rga'",
+			"cargo": {
+				"args": ["test", "--no-run", "--bin=rga", "--package=rga"],
+				"filter": {
+					"name": "rga",
+					"kind": "bin"
+				}
+			},
+			"args": [],
+			"cwd": "${workspaceFolder}"
+		},
+		{
+			"type": "lldb",
+			"request": "launch",
+			"name": "Debug executable 'rga-preproc'",
+			"cargo": {
+				"args": ["build", "--bin=rga-preproc", "--package=rga"],
+				"filter": {
+					"name": "rga-preproc",
+					"kind": "bin"
+				}
+			},
+			"args": ["exampledir/short.pdf"],
+			"cwd": "${workspaceFolder}"
+		},
+		{
+			"type": "lldb",
+			"request": "launch",
+			"name": "Debug unit tests in executable 'rga-preproc'",
+			"cargo": {
+				"args": ["test", "--no-run", "--bin=rga-preproc", "--package=rga"],
+				"filter": {
+					"name": "rga-preproc",
+					"kind": "bin"
+				}
+			},
+			"args": [],
+			"cwd": "${workspaceFolder}"
+		}
+	]
+}

src/adapters.rs

@@ -45,8 +45,11 @@ pub struct AdaptInfo<'a> {
     pub filepath_hint: &'a Path,
     /// true if filepath_hint is an actual file on the file system
     pub is_real_file: bool,
+    /// stream to read the file from. can be from a file or from some decoder
     pub inp: &'a mut dyn Read,
+    /// stream to write to. will be written to from a different thread
     pub oup: &'a mut (dyn Write + Send),
+    /// prefix every output line with this string to better indicate the file's location if it is in some archive
     pub line_prefix: &'a str,
     // pub adapt_subobject: &'a dyn Fn(AdaptInfo) -> Fallible<()>,
 }

src/preproc.rs

@@ -7,6 +7,7 @@ use path_clean::PathClean;
 const MAX_DB_BLOB_LEN: usize = 2_000_000;
 const ZSTD_LEVEL: i32 = 12;
 
+/// opens a LMDB cache
 pub fn open_cache_db() -> Result<std::sync::Arc<std::sync::RwLock<rkv::Rkv>>, Error> {
     let app_cache = cachedir::CacheDirConfig::new("rga").get_cache_dir()?;
 
@@ -30,6 +31,12 @@ pub fn open_cache_db() -> Result<std::sync::Arc<std::sync::RwLock<rkv::Rkv>>, Er
     Ok(db_arc)
 }
 
+/**
+ * preprocess a file as defined in `ai`.
+ *
+ * If a cache is passed, read/write to it.
+ *
+ */
 pub fn rga_preproc<'a>(
     ai: AdaptInfo<'a>,
     mb_db_arc: Option<std::sync::Arc<std::sync::RwLock<rkv::Rkv>>>,