From 88a4e2689786b2010386581d4380c5f781897d66 Mon Sep 17 00:00:00 2001
From: kageru <kageru@encode.moe>
Date: Sat, 18 May 2019 15:59:27 +0200
Subject: [PATCH] rename crate and add docstrings

---
 Cargo.lock |  2 +-
 Cargo.toml |  2 +-
 src/lib.rs | 28 +++++++++++++++++++++++++---
 3 files changed, 27 insertions(+), 5 deletions(-)

diff --git a/Cargo.lock b/Cargo.lock
index ad61e54..24da320 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -1,6 +1,6 @@
 # This file is automatically @generated by Cargo.
 # It is not intended for manual editing.
 [[package]]
-name = "rust-fzf"
+name = "fzf"
 version = "0.1.0"
 
diff --git a/Cargo.toml b/Cargo.toml
index dc423ec..5b2168f 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -1,5 +1,5 @@
 [package]
-name = "rust-fzf"
+name = "fzf"
 version = "0.1.0"
 authors = ["kageru <kageru@encode.moe>"]
 edition = "2018"
diff --git a/src/lib.rs b/src/lib.rs
index 1a8af80..c0dc25c 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -1,3 +1,9 @@
+#![crate_name = "fzf"]
+
+
+/**
+ * Return a filtered `Vec` of elements that contain the substring `needle`.
+ */
 pub fn filter_substring<'a>(needle: &str, haystack: &Vec<&'a str>) -> Vec<&'a str> {
     return haystack
         .iter()
@@ -6,6 +12,11 @@ pub fn filter_substring<'a>(needle: &str, haystack: &Vec<&'a str>) -> Vec<&'a st
         .collect();
 }
 
+/**
+ * Return a filtered `Vec` of elements which `needle` is a subsequence of.
+ * (I know what I’m doing. Let me end a sentence with a preposition.) :^)
+ * See `is_subsequence` for more information on that.
+ */
 pub fn filter_subsequence<'a>(needle: &str, haystack: &Vec<&'a str>) -> Vec<&'a str> {
     return haystack
         .iter()
@@ -14,9 +25,20 @@ pub fn filter_subsequence<'a>(needle: &str, haystack: &Vec<&'a str>) -> Vec<&'a
         .collect();
 }
 
-fn is_subsequence(needle: &str, string: &str) -> bool {
-    // we need to explicitly convert here to iterate over chars
-    // (UTF-8, so possibly multiple bytes long)
+/**
+ * Check whether the needle is a subsequence of the string.
+ * This is the case if string contains all of the characters in needle in the correct order, but
+ * not necessarily in succession.
+ *
+ * ```
+ * use fzf::is_subsequence;
+ * // ‘as’ is contained in ‘a(d)s’
+ * assert!(is_subsequence("as", "ads"));
+ * // but not in ‘sa’
+ * assert!(!is_subsequence("as", "sa"));
+ * ```
+ */
+pub fn is_subsequence(needle: &str, string: &str) -> bool {
     let mut chars = string.chars();
     'needle: for nc in needle.chars() {
         for c in &mut chars {