From ff2f828a531d23ee087940fed20e8798fdf2c204 Mon Sep 17 00:00:00 2001 From: Brian Aker Date: Fri, 18 Dec 2009 17:28:01 -0800 Subject: [PATCH] Clean up docs. --- Makefile.am | 2 + docs/Makefile.am | 316 +++++++++++++++++++++--------------- docs/hashkit_create.pod | 57 +++++++ docs/hashkit_functions.pod | 54 ++++++ docs/hashkit_value.pod | 41 +++++ docs/memcached_servers.pod | 24 +-- docs/memcached_strerror.pod | 2 +- tests/include.am | 3 +- 8 files changed, 353 insertions(+), 146 deletions(-) create mode 100644 docs/hashkit_create.pod create mode 100644 docs/hashkit_functions.pod create mode 100644 docs/hashkit_value.pod diff --git a/Makefile.am b/Makefile.am index 09db5e94..da5f16e2 100644 --- a/Makefile.am +++ b/Makefile.am @@ -18,6 +18,8 @@ EXTRA_DIST = README.FIRST SUBDIRS = docs libhashkit +test-docs: + (cd docs && make test-docs) include libmemcached/include.am include clients/include.am include tests/include.am diff --git a/docs/Makefile.am b/docs/Makefile.am index 9a4ee49a..11046090 100644 --- a/docs/Makefile.am +++ b/docs/Makefile.am @@ -1,120 +1,126 @@ CLEANFILES= *.1 *.3 -EXTRA_DIST = libmemcached.pod\ - libmemcachedutil.pod\ - memcached_flush.pod\ - memcached_dump.pod\ - memcached_stats.pod\ - memrm.pod\ - memerror.pod\ - libmemcached_examples.pod\ - memcached_get.pod\ - memcached_strerror.pod\ - memslap.pod\ - memcached_auto.pod\ - memcached_quit.pod\ - memcached_verbosity.pod\ - memstat.pod\ - memcached_behavior.pod\ - memcached_callback.pod\ - memcached_server_st.pod\ - memcapable.pod \ - memcat.pod\ - memcached_create.pod\ - memcached_pool.pod\ - memcached_servers.pod\ - memcp.pod\ - memcached_delete.pod\ - memcached_set.pod\ - memcached_version.pod\ - memflush.pod\ - memdump.pod\ - memcached_flush_buffers.pod\ - memcached_analyze.pod\ - memcached_generate_hash_value.pod\ - memcached_memory_allocators.pod\ - memcached_user_data.pod - -man_MANS = libmemcached.3\ - libmemcached_examples.3\ - memcapable.1\ - memcat.1\ - memcp.1\ - memerror.1\ - memflush.1\ - memdump.1\ - memrm.1\ - memslap.1\ - memstat.1\ - memcached_add.3\ - memcached_add_by_key.3\ - memcached_append.3\ - memcached_append_by_key.3\ - memcached_analyze.3\ - memcached_behavior_get.3\ - memcached_behavior_set.3\ - memcached_callback_get.3\ - memcached_callback_set.3\ - memcached_cas.3\ - memcached_cas_by_key.3\ - memcached_clone.3\ - memcached_create.3\ - memcached_decrement.3\ - memcached_decrement_with_initial.3\ - memcached_delete.3\ - memcached_delete_by_key.3\ - memcached_fetch.3\ - memcached_fetch_execute.3\ - memcached_fetch_result.3\ - memcached_free.3\ - memcached_get.3\ - memcached_get_by_key.3\ - memcached_increment.3\ - memcached_increment_with_initial.3\ - memcached_mget.3\ - memcached_mget_by_key.3\ - memcached_mget_execute.3 \ - memcached_mget_execute_by_key.3 \ - memcached_prepend.3\ - memcached_prepend_by_key.3\ - memcached_replace.3\ - memcached_replace_by_key.3\ - memcached_server_add.3\ - memcached_server_count.3\ - memcached_server_list.3\ - memcached_server_list_append.3\ - memcached_server_list_count.3\ - memcached_server_list_free.3\ - memcached_server_push.3\ - memcached_servers_parse.3\ - memcached_set.3\ - memcached_set_by_key.3\ - memcached_stat.3\ - memcached_stat_get_keys.3\ - memcached_stat_get_value.3\ - memcached_stat_servername.3\ - memcached_strerror.3\ - memcached_quit.3\ - memcached_verbosity.3\ - memcached_lib_version.3\ - memcached_version.3\ - memcached_flush_buffers.3\ - memcached_dump.3\ - memcached_generate_hash_value.3\ - memcached_set_memory_allocators.3\ - memcached_get_memory_allocators.3\ - memcached_set_user_data.3\ - memcached_get_user_data.3 +EXTRA_DIST = \ + hashkit_create.pod \ + hashkit_functions.pod \ + hashkit_value.pod \ + libmemcached.pod \ + libmemcached_examples.pod \ + libmemcachedutil.pod \ + memcached_analyze.pod \ + memcached_auto.pod \ + memcached_behavior.pod \ + memcached_callback.pod \ + memcached_create.pod \ + memcached_delete.pod \ + memcached_dump.pod \ + memcached_flush.pod \ + memcached_flush_buffers.pod \ + memcached_generate_hash_value.pod \ + memcached_get.pod \ + memcached_memory_allocators.pod \ + memcached_pool.pod \ + memcached_quit.pod \ + memcached_server_st.pod \ + memcached_servers.pod \ + memcached_set.pod \ + memcached_stats.pod \ + memcached_strerror.pod \ + memcached_user_data.pod \ + memcached_verbosity.pod \ + memcached_version.pod \ + memcapable.pod \ + memcat.pod \ + memcp.pod \ + memdump.pod \ + memerror.pod \ + memflush.pod \ + memrm.pod \ + memslap.pod \ + memstat.pod + +man_MANS = \ + libmemcached.3 \ + libmemcached_examples.3 \ + memcached_add.3 \ + memcached_add_by_key.3 \ + memcached_analyze.3 \ + memcached_append.3 \ + memcached_append_by_key.3 \ + memcached_behavior_get.3 \ + memcached_behavior_set.3 \ + memcached_callback_get.3 \ + memcached_callback_set.3 \ + memcached_cas.3 \ + memcached_cas_by_key.3 \ + memcached_clone.3 \ + memcached_create.3 \ + memcached_decrement.3 \ + memcached_decrement_with_initial.3 \ + memcached_delete.3 \ + memcached_delete_by_key.3 \ + memcached_dump.3 \ + memcached_fetch.3 \ + memcached_fetch_execute.3 \ + memcached_fetch_result.3 \ + memcached_flush_buffers.3 \ + memcached_free.3 \ + memcached_generate_hash_value.3 \ + memcached_get.3 \ + memcached_get_by_key.3 \ + memcached_get_memory_allocators.3 \ + memcached_get_user_data.3 \ + memcached_increment.3 \ + memcached_increment_with_initial.3 \ + memcached_lib_version.3 \ + memcached_mget.3 \ + memcached_mget_by_key.3 \ + memcached_mget_execute.3 \ + memcached_mget_execute_by_key.3 \ + memcached_prepend.3 \ + memcached_prepend_by_key.3 \ + memcached_quit.3 \ + memcached_replace.3 \ + memcached_replace_by_key.3 \ + memcached_server_add.3 \ + memcached_server_count.3 \ + memcached_server_list.3 \ + memcached_server_list_append.3 \ + memcached_server_list_count.3 \ + memcached_server_list_free.3 \ + memcached_server_push.3 \ + memcached_servers_parse.3 \ + memcached_set.3 \ + memcached_set_by_key.3 \ + memcached_set_memory_allocators.3 \ + memcached_set_user_data.3 \ + memcached_stat.3 \ + memcached_stat_get_keys.3 \ + memcached_stat_get_value.3 \ + memcached_stat_servername.3 \ + memcached_strerror.3 \ + memcached_verbosity.3 \ + memcached_version.3 \ + memcapable.1 \ + memcat.1 \ + memcp.1 \ + memdump.1 \ + memerror.1 \ + memflush.1 \ + memrm.1 \ + memslap.1 \ + memstat.1 if BUILD_LIBMEMCACHEDUTIL -man_MANS+= libmemcachedutil.3 \ - memcached_pool_behavior_set.3 \ - memcached_pool_behavior_get.3 \ - memcached_pool_create.3 \ - memcached_pool_destroy.3 \ - memcached_pool_push.3 \ - memcached_pool_pop.3 +man_MANS+= \ + libmemcachedutil.3 \ + memcached_pool_behavior_set.3 \ + memcached_pool_behavior_get.3 \ + memcached_pool_create.3 \ + memcached_pool_destroy.3 \ + memcached_pool_push.3 \ + memcached_pool_pop.3 endif @@ -382,36 +388,84 @@ memdump.1: memdump.pod memflush.1: memflush.pod ${POD2MAN} -c "libmemcached" -r "" -s 1 ${top_srcdir}/docs/memflush.pod > memflush.1 -test: +hashkit_create.3: hashkit_create.pod + ${POD2MAN} -c "libhashkit" -r "" -s 3 ${top_srcdir}/docs/hashkit_create.pod > hashkit_create.3 + +hashkit_clone.3: hashkit_create.pod + ${POD2MAN} -c "libhashkit" -r "" -s 3 ${top_srcdir}/docs/hashkit_create.pod > hashkit_clone.3 + +hashkit_free.3: hashkit_create.pod + ${POD2MAN} -c "libhashkit" -r "" -s 3 ${top_srcdir}/docs/hashkit_create.pod > hashkit_free.3 + +hashkit_is_allocated.3: hashkit_create.pod + ${POD2MAN} -c "libhashkit" -r "" -s 3 ${top_srcdir}/docs/hashkit_create.pod > hashkit_is_allocated.3 + +hashkit_functions.3: hashkit_functions.pod + ${POD2MAN} -c "libhashkit" -r "" -s 3 ${top_srcdir}/docs/hashkit_functions.pod > hashkit_functions.3 + +hashkit_fnv1_64.3: hashkit_functions.pod + ${POD2MAN} -c "libhashkit" -r "" -s 3 ${top_srcdir}/docs/hashkit_functions.pod > hashkit_fnv1_64.3 + +hashkit_fnv1a_64.3: hashkit_functions.pod + ${POD2MAN} -c "libhashkit" -r "" -s 3 ${top_srcdir}/docs/hashkit_functions.pod > hashkit_fnv1a_64.3 + +hashkit_fnv1_32.3: hashkit_functions.pod + ${POD2MAN} -c "libhashkit" -r "" -s 3 ${top_srcdir}/docs/hashkit_functions.pod > hashkit_fnv1_32.3 + +hashkit_fnv1a_32.3: hashkit_functions.pod + ${POD2MAN} -c "libhashkit" -r "" -s 3 ${top_srcdir}/docs/hashkit_functions.pod > hashkit_fnv1a_32.3 + +hashkit_crc32.3: hashkit_functions.pod + ${POD2MAN} -c "libhashkit" -r "" -s 3 ${top_srcdir}/docs/hashkit_functions.pod > hashkit_crc32.3 + +hashkit_hsieh.3: hashkit_functions.pod + ${POD2MAN} -c "libhashkit" -r "" -s 3 ${top_srcdir}/docs/hashkit_functions.pod > hashkit_hsieh.3 + +hashkit_murmur.3: hashkit_functions.pod + ${POD2MAN} -c "libhashkit" -r "" -s 3 ${top_srcdir}/docs/hashkit_functions.pod > hashkit_murmur.3 + +hashkit_jenkins.3: hashkit_functions.pod + ${POD2MAN} -c "libhashkit" -r "" -s 3 ${top_srcdir}/docs/hashkit_functions.pod > hashkit_jenkins.3 + +hashkit_md5.3: hashkit_functions.pod + ${POD2MAN} -c "libhashkit" -r "" -s 3 ${top_srcdir}/docs/hashkit_functions.pod > hashkit_md5.3 + +hashkit_value.3: hashkit_value.pod + ${POD2MAN} -c "libhashkit" -r "" -s 3 ${top_srcdir}/docs/hashkit_value.pod > hashkit_value.3 + +test-docs: + podchecker $(top_srcdir)/docs/hashkit_create.pod + podchecker $(top_srcdir)/docs/hashkit_functions.pod + podchecker $(top_srcdir)/docs/hashkit_value.pod podchecker $(top_srcdir)/docs/libmemcached.pod - podchecker $(top_srcdir)/docs/memcached_flush.pod - podchecker $(top_srcdir)/docs/memcached_stats.pod - podchecker $(top_srcdir)/docs/memrm.pod - podchecker $(top_srcdir)/docs/memerror.pod podchecker $(top_srcdir)/docs/libmemcached_examples.pod - podchecker $(top_srcdir)/docs/memcached_get.pod - podchecker $(top_srcdir)/docs/memcached_strerror.pod - podchecker $(top_srcdir)/docs/memslap.pod podchecker $(top_srcdir)/docs/memcached_auto.pod - podchecker $(top_srcdir)/docs/memcached_quit.pod - podchecker $(top_srcdir)/docs/memcached_verbosity.pod - podchecker $(top_srcdir)/docs/memstat.pod podchecker $(top_srcdir)/docs/memcached_behavior.pod podchecker $(top_srcdir)/docs/memcached_callback.pod - podchecker $(top_srcdir)/docs/memcached_server_st.pod - podchecker $(top_srcdir)/docs/memcat.pod podchecker $(top_srcdir)/docs/memcached_create.pod - podchecker $(top_srcdir)/docs/memcached_servers.pod - podchecker $(top_srcdir)/docs/memcp.pod podchecker $(top_srcdir)/docs/memcached_delete.pod - podchecker $(top_srcdir)/docs/memcached_set.pod - podchecker $(top_srcdir)/docs/memcached_version.pod - podchecker $(top_srcdir)/docs/memflush.pod + podchecker $(top_srcdir)/docs/memcached_flush.pod podchecker $(top_srcdir)/docs/memcached_flush_buffers.pod - podchecker $(top_srcdir)/docs/memcached_pool.pod + podchecker $(top_srcdir)/docs/memcached_get.pod podchecker $(top_srcdir)/docs/memcached_memory_allocators.pod + podchecker $(top_srcdir)/docs/memcached_pool.pod + podchecker $(top_srcdir)/docs/memcached_quit.pod + podchecker $(top_srcdir)/docs/memcached_server_st.pod + podchecker $(top_srcdir)/docs/memcached_servers.pod + podchecker $(top_srcdir)/docs/memcached_set.pod + podchecker $(top_srcdir)/docs/memcached_stats.pod + podchecker $(top_srcdir)/docs/memcached_strerror.pod podchecker $(top_srcdir)/docs/memcached_user_data.pod + podchecker $(top_srcdir)/docs/memcached_verbosity.pod + podchecker $(top_srcdir)/docs/memcached_version.pod podchecker $(top_srcdir)/docs/memcapable.pod + podchecker $(top_srcdir)/docs/memcat.pod + podchecker $(top_srcdir)/docs/memcp.pod + podchecker $(top_srcdir)/docs/memerror.pod + podchecker $(top_srcdir)/docs/memflush.pod + podchecker $(top_srcdir)/docs/memrm.pod + podchecker $(top_srcdir)/docs/memslap.pod + podchecker $(top_srcdir)/docs/memstat.pod html-local: pod2htmltree "/libmemcached" . diff --git a/docs/hashkit_create.pod b/docs/hashkit_create.pod new file mode 100644 index 00000000..bcd5390c --- /dev/null +++ b/docs/hashkit_create.pod @@ -0,0 +1,57 @@ +=head1 NAME + +hashkit_create, hashkit_clone, hashkit_free, hashkit_is_allocated - +Create and destroy hashkit objects + +=head1 LIBRARY + +C Library for hashing algorithms (libhashkit, -lhashkit) + +=head1 SYNOPSIS + + #include + + hashkit_st *hashkit_create(hashkit_st *hash); + + hashkit_st *hashkit_clone(hashkit_st *destination, const hashkit_st *ptr); + + void hashkit_free(hashkit_st *hash); + + bool hashkit_is_allocated(const hashkit_st *hash); + +=head1 DESCRIPTION + +The hashkit_create() function initializes a hashkit object for use. If +you pass a NULL argument for hash, then the memory for the object is +allocated. If you specify a pre-allocated piece of memory, that is +initialized for use. + +The hashkit_clone() function initializes a hashkit object much like +hashkit_create(), but instead of using default settings it will use +the settings of the ptr hashkit object. + +The hashkit_free() frees any resources being consumed by the hashkit +objects that were initialized with hashkit_create() or hashkit_clone(). + +The hashkit_is_allocated() reports where the memory was allocated +for a hashkit object. + +=head1 RETURN VALUE + +hashkit_create() and hashkit_clone() will return NULL on failure or +non-NULL on success. + +hashkit_is_allocated() returns true if the memory for the hashkit +object was allocated inside of hashkit_create() or hashkit_clone(), +otherwise it is false and was user-supplied memory. + +=head1 HOME + +To find out more information please check: +L + +=head1 AUTHOR + +Brian Aker, Ebrian@tangent.orgE + +=cut diff --git a/docs/hashkit_functions.pod b/docs/hashkit_functions.pod new file mode 100644 index 00000000..4af84182 --- /dev/null +++ b/docs/hashkit_functions.pod @@ -0,0 +1,54 @@ +=head1 NAME + +hashkit_default, hashkit_fnv1_64, hashkit_fnv1a_64, hashkit_fnv1_32, +hashkit_fnv1a_32, hashkit_crc32, hashkit_hsieh, hashkit_murmur, +hashkit_jenkins, hashkit_md5 - Various hash functions to use for +calculating values for keys + +=head1 LIBRARY + +C Library for hashing algorithms (libhashkit, -lhashkit) + +=head1 SYNOPSIS + + #include + + uint32_t hashkit_default(const char *key, size_t key_length); + uint32_t hashkit_fnv1_64(const char *key, size_t key_length); + uint32_t hashkit_fnv1a_64(const char *key, size_t key_length); + uint32_t hashkit_fnv1_32(const char *key, size_t key_length); + uint32_t hashkit_fnv1a_32(const char *key, size_t key_length); + uint32_t hashkit_crc32(const char *key, size_t key_length); + uint32_t hashkit_hsieh(const char *key, size_t key_length); + uint32_t hashkit_murmur(const char *key, size_t key_length); + uint32_t hashkit_jenkins(const char *key, size_t key_length); + uint32_t hashkit_md5(const char *key, size_t key_length); + +=head1 DESCRIPTION + +These functions generate hash values from a key using a variety of +algorithms. These functions can be used standalone, or as arguments +to hashkit_set_hash_fn(3) or hashkit_set_continuum_hash_fn(3). + +The hashkit_hsieh() is only available if the library is built with +the appropriate flag enabled. + +=head1 RETURN VALUE + +A 32-bit hash value. + +=head1 HOME + +To find out more information please check: +L + +=head1 AUTHOR + +Brian Aker, Ebrian@tangent.orgE + +=head1 SEE ALSO + +hashkit_create(3) hashkit_value(3) hashkit_set_hash_fn(3) +hashkit_set_continuum_hash_fn(3) + +=cut diff --git a/docs/hashkit_value.pod b/docs/hashkit_value.pod new file mode 100644 index 00000000..db594bc9 --- /dev/null +++ b/docs/hashkit_value.pod @@ -0,0 +1,41 @@ +=head1 NAME + +hashkit_value - Generate a value for the given key + +=head1 LIBRARY + +C Library for hashing algorithms (libhashkit, -lhashkit) + +=head1 SYNOPSIS + + #include + + uint32_t hashkit_value(hashkit_st *hash, + const char *key, + size_t key_length); + +=head1 DESCRIPTION + +The hashkit_value() function generates a 32-bit hash value from the +given key and key_length. The hash argument is an initialized hashkit +object, and distribution type and hash function is used from this +object while generating the value. + +=head1 RETURN VALUE + +A 32-bit hash value. + +=head1 HOME + +To find out more information please check: +L + +=head1 AUTHOR + +Brian Aker, Ebrian@tangent.orgE + +=head1 SEE ALSO + +hashkit_create(3) hashkit_set_distribution(3) hashkit_set_hash_fn(3) + +=cut diff --git a/docs/memcached_servers.pod b/docs/memcached_servers.pod index 80241c6a..f4f789d4 100644 --- a/docs/memcached_servers.pod +++ b/docs/memcached_servers.pod @@ -34,13 +34,13 @@ C Client Library for memcached (libmemcached, -lmemcached) memcached_server_st *list); memcached_server_st * - memcached_server_by_key (memcached_st *ptr, - const char *key, size_t key_length, + memcached_server_by_key (memcached_st *ptr, + const char *key, size_t key_length, memcached_return_t *error); - memcached_server_st * + memcached_server_st * memcached_server_get_last_disconnect (memcached_st *ptr) - + =head1 DESCRIPTION @@ -59,17 +59,17 @@ currently used structure). memcached_server_add() pushes a single TCP server into the C structure. This server will be placed at the end. Duplicate servers are allowed, so duplication is not checked. Executing this function with the -C behavior set will result in a +C behavior set will result in a C. memcached_server_add_udp() pushes a single UDP server into the C structure. This server will be placed at the end. Duplicate servers are allowed, so duplication is not checked. Executing this function with out -setting the C behavior will result in a +setting the C behavior will result in a C. -memcached_server_add_unix_socket() pushes a single UNIX socket into the -C structure. This UNIX socket will be placed at the end. +memcached_server_add_unix_socket() pushes a single UNIX socket into the +C structure. This UNIX socket will be placed at the end. Duplicate servers are allowed, so duplication is not checked. The length of the filename must be one character less then MEMCACHED_MAX_HOST_LENGTH. @@ -85,9 +85,9 @@ from its original structure and must be freed. If NULL is returned you should consult *error. The returning structure should be freed with memcached_server_free(). -memcached_server_get_last_disconnect() returns a pointer to the last server -for which there was a connection problem. It does not mean this particular -server is currently dead but if the library is reporting a server is, +memcached_server_get_last_disconnect() returns a pointer to the last server +for which there was a connection problem. It does not mean this particular +server is currently dead but if the library is reporting a server is, the returned server is a very good candidate. =head1 RETURN @@ -96,7 +96,7 @@ Varies, see particular functions. =head1 HOME -To find out more information please check: +To find out more information please check: L =head1 AUTHOR diff --git a/docs/memcached_strerror.pod b/docs/memcached_strerror.pod index 8386c312..64ef5957 100644 --- a/docs/memcached_strerror.pod +++ b/docs/memcached_strerror.pod @@ -1,7 +1,7 @@ =head1 NAME memcached_strerror - Get error string - + =head1 LIBRARY C Client Library for memcached (libmemcached, -lmemcached) diff --git a/tests/include.am b/tests/include.am index 20b0ee49..896ba139 100644 --- a/tests/include.am +++ b/tests/include.am @@ -82,12 +82,11 @@ client-record: sh tests/t/memslap.test > tests/r/memslap.res sh tests/t/memstat.test > tests/r/memstat.res -test: tests/testapp tests/testplus library_test memcapable libmhashkit_test +test: test-docs tests/testapp tests/testplus library_test memcapable libmhashkit_test echo "Tests completed" library_test: tests/testapp -# tests/testplus libmhashkit_test: libhashkit tests/testhashkit -- 2.30.2