From 90c32e1bd564b3697037ecdae858d5155fb7e8c1 Mon Sep 17 00:00:00 2001
From: TudbuT <tudbut@tudbut.de>
Date: Sun, 1 Jan 2023 19:36:04 +0100
Subject: [PATCH] add doc comments and categorize crate

---
 Cargo.toml | 14 ++++++++++++++
 src/lib.rs | 14 ++++++++++++++
 2 files changed, 28 insertions(+)

diff --git a/Cargo.toml b/Cargo.toml
index 52d11db..452b79d 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -5,5 +5,19 @@ edition = "2021"
 repository = "https://github.com/tudbut/readformat"
 license = "MIT"
 description = "Very small format reader"
+keywords = [
+    "readf",
+    "format",
+    "parser",
+    "parse",
+    "reader",
+    "formatting",
+]
+categories = [
+    "parser-implementations",
+    "encoding",
+    "parsing",
+    "text-processing"
+]
 
 [dependencies]
diff --git a/src/lib.rs b/src/lib.rs
index d6200ba..002bbe1 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -1,4 +1,12 @@
 
+/// The inverse of format!().
+/// The format argument is the format string, and the s argument is the string to match the format
+/// against.
+///
+/// Examples:
+///  `readf("Hello, {}!", "Hello, world!")` => `Some(vec!["world"])`
+///  `readf("I hope {} are {}!", "I hope you are doing well!")` => `Some(vec!["you", "well"])`
+///  `readf("Goodbye, {}!", "Hello, world!")` => `None`
 pub fn readf(format: &str, mut s: &str) -> Option<Vec<String>> {
     if !format.contains("{}") {
         return if format == s { Some(vec![]) } else { None };
@@ -50,6 +58,12 @@ pub fn readf(format: &str, mut s: &str) -> Option<Vec<String>> {
     }
 }
 
+/// Convenience function for single-item format strings. Extra items are dropped.
+///
+/// Examples:
+///  `readf1("Hello, {}!", "Hello, world!")` => `Some("world")`
+///  `readf1("I hope {} are doing well!", "I hope you are doing well!")` => `Some("you")`
+///  `readf1("Goodbye, {}!", "Hello, world!")` => `None`
 pub fn readf1(format: &str, s: &str) -> Option<String> {
     let r = readf(format, s);
     r.map(|x| if x.len() == 0 { "".into() } else { x[0].clone() })