From fa21c55adb75551452241369424a146c7acb71a4 Mon Sep 17 00:00:00 2001
From: Andre Noll <maan@systemlinux.org>
Date: Wed, 24 Dec 2008 13:51:29 +0100
Subject: [PATCH] bloom: Add some source documentation.

---
 bloom.c  | 25 ++++++++++++++++++-------
 bloom.h  | 14 ++++++++++++++
 create.c |  2 ++
 3 files changed, 34 insertions(+), 7 deletions(-)

diff --git a/bloom.c b/bloom.c
index f7a9b1a..9b66b90 100644
--- a/bloom.c
+++ b/bloom.c
@@ -114,13 +114,11 @@ int bloom_test_and_insert(const uint8_t *data, size_t len, struct bloom *b)
 	return !ret;
 }
 
-int bloom_test_and_insert_string(const char *str, struct bloom *b)
-{
-	uint32_t len = strlen(str);
-
-	return bloom_test_and_insert((const uint8_t *)str, len, b);
-}
-
+/**
+ * Deallocate a bloom filter.
+ *
+ * \param b The filter to deallocate.
+ */
 void bloom_free(struct bloom *b)
 {
 	if (!b)
@@ -129,6 +127,12 @@ void bloom_free(struct bloom *b)
 	free(b);
 }
 
+/**
+ * Initialize a bloom filter.
+ *
+ * \param order Use a filter containing 2^order bits.
+ * \param num_hash_functions Set that many bits in the filter per entry.
+ */
 int bloom_init(unsigned order, unsigned num_hash_functions,
 		struct bloom **result)
 {
@@ -145,6 +149,13 @@ int bloom_init(unsigned order, unsigned num_hash_functions,
 
 #ifdef TEST_BLOOM
 
+int bloom_test_and_insert_string(const char *str, struct bloom *b)
+{
+	uint32_t len = strlen(str);
+
+	return bloom_test_and_insert((const uint8_t *)str, len, b);
+}
+
 void add_stdin(struct bloom *b)
 {
 	char buf[255];
diff --git a/bloom.h b/bloom.h
index afb2298..e7f3cd3 100644
--- a/bloom.h
+++ b/bloom.h
@@ -1,8 +1,22 @@
+/*
+ * Copyright (C) 2008 Andre Noll <maan@systemlinux.org>
+ *
+ * Licensed under the GPL v2. For licencing details see COPYING.
+ */
+
+/** \file bloom.h Struct bloom and bloom filter functions. */
+
+/** Describes one instance of a bloom filter. */
 struct bloom {
+	/** The bloom filter is of size 2^order bits. */
 	unsigned order;
+	/** Set that many bits in the filter per entry. */
 	unsigned num_hash_functions;
+	/** How many entries have been inserted so far. */
 	uint64_t num_entries;
+	/** Number of bits currently set. */
 	uint64_t num_set_bits;
+	/** The bit array. */
 	uint8_t *filter;
 };
 
diff --git a/create.c b/create.c
index 1b4ba88..51583a6 100644
--- a/create.c
+++ b/create.c
@@ -31,7 +31,9 @@ static int consider_bloom(struct stat64 *s)
 	return 1;
 }
 
+/** Data size to hash for the global bloom filter. */
 #define GLOBAL_BLOOM_BUF_SIZE (sizeof(ino_t) + sizeof(dev_t) + sizeof(off_t))
+/** For the user bloom filter also the uid is being hashed. */
 #define USER_BLOOM_BUF_SIZE (GLOBAL_BLOOM_BUF_SIZE + sizeof(uid_t))
 
 static void make_bloom_buf(struct stat64 *s, uint8_t buf[USER_BLOOM_BUF_SIZE])
-- 
2.39.2