Merge lp:~kent/libmemcached/KBDocs1 into lp:~tangent-org/libmemcached/trunk

[KentBozlinski]

Cleaned up Grammar and some formatting of text in some of the docs. No big changes, just cleanup.

[lp:~kent/libmemcached/KBDocs1]

937. By Kent <kent@KentLaptop> on 2011-04-18

Merge of Brian with Doc

=== modified file 'docs/hashkit_create.rst'
--- docs/hashkit_create.rst	2011-04-14 04:27:08 +0000
+++ docs/hashkit_create.rst	2011-04-18 19:22:31 +0000
@@ -22,9 +22,9 @@
 
 .. code-block:: perl
 
-   #include <libmemcached/hashkit.h>
+#include <libmemcached/hashkit.h>
  
-   hashkit_st *hashkit_create(hashkit_st *hash);
+hashkit_st *hashkit_create(hashkit_st *hash);
  
    hashkit_st *hashkit_clone(hashkit_st *destination, const hashkit_st *ptr);
  

=== modified file 'docs/libmemcached.rst'
--- docs/libmemcached.rst	2011-04-14 04:27:08 +0000
+++ docs/libmemcached.rst	2011-04-18 19:22:31 +0000
@@ -6,10 +6,17 @@
 SYNOPSIS
 --------
 
-#include <libmemcached/memcached.h>
-
-Compile and link with -lmemcached
-
+libMemcached is an open source C/C++ client library and tools for the memcached server (http://danga.com/memcached). It has been designed to be light on memory usage, thread safe, and provide full access to server side methods.
+
+libMemcached was designed to provide the greatest number of options to use Memcached. Some of the features provided:
+
+1. Asynchronous and Synchronous Transport Support.
+2. Consistent Hashing and Distribution.
+3. Tunable Hashing algorithm to match keys.
+4. Access to large object support.
+5. Local replication.
+6. A complete reference guide and documentation to the API.
+7. Tools to Manage your Memcached networks.
 
 -----------
 DESCRIPTION
@@ -21,14 +28,14 @@
 applications by alleviating database load." `http://danga.com/memcached/ <http://danga.com/memcached/>`_
 
 \ **libmemcached**\  is a small, thread-safe client library for the
-memcached protocol. The code has all been written with an eye to allow
+memcached protocol. The code has all been written to allow
 for both web and embedded usage. It handles the work behind routing
-particular keys to specific servers that you specify (and values are
-matched based on server order as supplied by you). It implements both
-a modula and consistent method of object distribution.
+individual keys to specific servers specified by the developer (and values are
+matched based on server order as supplied by the user). It implements
+a modular and consistent method of object distribution.
 
 There are multiple implemented routing and hashing methods. See the
-memcached_behavior_set() manpage.
+memcached_behavior_set() manpage for more information.
 
 All operations are performed against a \ ``memcached_st``\  structure.
 These structures can either be dynamically allocated or statically
@@ -117,9 +124,9 @@
 ---------------------
 
 
-When using threads or forked processes it is important to keep an instance
+When using threads or forked processes it is important to keep one instance
 of \ ``memcached_st``\  per process or thread. Without creating your own locking
-structures you can not share a single \ ``memcached_st``\ . You can though call
+structures you can not share a single \ ``memcached_st``\ . However, you can call
 memcached_quit(3) on a \ ``memcached_st``\  and then use the resulting cloned
 structure.
 

=== modified file 'docs/memcached_callback.rst'
--- docs/memcached_callback.rst	2011-04-14 04:27:08 +0000
+++ docs/memcached_callback.rst	2011-04-18 19:22:31 +0000
@@ -41,73 +41,71 @@
 memcached_callback_set() changes the function/structure assigned by a
 callback flag. No connections are reset.
 
-You can use MEMCACHED_CALLBACK_USER_DATA to provide custom context if required for any 
-of the callbacks
+You can use MEMCACHED_CALLBACK_USER_DATA to provide custom context if required for any of the callbacks.
 
 
 .. c:var:: MEMCACHED_CALLBACK_CLEANUP_FUNCTION
  
- When memcached_delete() is called this function will be excuted. At the
- point of its execution all connections have been closed.
+When memcached_delete() is called this function will be excuted. At the point of its execution all connections are closed.
  
 
 
 .. c:var:: MEMCACHED_CALLBACK_CLONE_FUNCTION
  
- When memcached_delete() is called this function will be excuted. At the
- point of its execution all connections have been closed.
+When memcached_delete() is called this function will be excuted. At the
+point of its execution all connections are closed.
  
 
 
 .. c:var:: MEMCACHED_CALLBACK_PREFIX_KEY
  
- You can set a value which will be used to create a domain for your keys.
- The value specified here will be prefixed to each of your keys. The value can not
- be greater then MEMCACHED_PREFIX_KEY_MAX_SIZE - 1 and will reduce MEMCACHED_MAX_KEY by
- the value of your key. The prefix key is only applied to the primary key,
- not the master key. MEMCACHED_FAILURE will be returned if no key is set. In the case
- of a key which is too long MEMCACHED_BAD_KEY_PROVIDED will be returned.
+You can set a value which will be used to create a domain for your keys.
+The value specified here will be prefixed to each of your keys. The value can not be greater then MEMCACHED_PREFIX_KEY_MAX_SIZE - 1 and will reduce MEMCACHED_MAX_KEY by the value of your key. 
+
+The prefix key is only applied to the primary key, not the master key. MEMCACHED_FAILURE will be returned if no key is set. In the case of a key which is too long, MEMCACHED_BAD_KEY_PROVIDED will be returned.
  
- If you set a value with the value being NULL then the prefix key is disabled.
+If you set a value with the value being NULL then the prefix key is disabled.
 
 
 .. c:var:: MEMCACHED_CALLBACK_USER_DATA
  
- This allows you to store a pointer to a specifc piece of data. This can be
- retrieved from inside of memcached_fetch_execute(). Cloning a memcached_st
- will copy the pointer to the clone.
+This allows you to store a pointer to a specifc piece of data. This can be
+retrieved from inside of memcached_fetch_execute(). Cloning a memcached_st
+will copy the pointer to the clone.
  
 
 
 .. c:var:: MEMCACHED_CALLBACK_MALLOC_FUNCTION
  
- DEPRECATED: use memcached_set_memory_allocators instead.
+DEPRECATED: use memcached_set_memory_allocators instead.
  
 
 
 .. c:var:: MEMCACHED_CALLBACK_REALLOC_FUNCTION
  
- DEPRECATED: use memcached_set_memory_allocators instead.
+DEPRECATED: use memcached_set_memory_allocators instead.
  
 
 
 .. c:var:: MEMCACHED_CALLBACK_FREE_FUNCTION
  
- DEPRECATED: use memcached_set_memory_allocators instead.
+DEPRECATED: use memcached_set_memory_allocators instead.
  
 
 
 .. c:var:: MEMCACHED_CALLBACK_GET_FAILURE
  
- This function implements the read through cache behavior. On failure of retrieval this callback will be called. 
- You are responsible for populating the result object provided. This result object will then be stored in the server and
- returned to the calling process. You must clone the memcached_st in order to
- make use of it. The value will be stored only if you return
- MEMCACHED_SUCCESS or MEMCACHED_BUFFERED. Returning MEMCACHED_BUFFERED will
- cause the object to be buffered and not sent immediatly (if this is the default behavior based on your connection setup this will happen automatically).
+This function implements the read through cache behavior. On failure of retrieval this callback will be called. 
+
+You are responsible for populating the result object provided. This result object will then be stored in the server and returned to the calling process. 
+
+You must clone the memcached_st in order to
+make use of it. The value will be stored only if you return
+MEMCACHED_SUCCESS or MEMCACHED_BUFFERED. Returning MEMCACHED_BUFFERED will
+cause the object to be buffered and not sent immediatly (if this is the default behavior based on your connection setup this will happen automatically).
  
- The prototype for this is:
- memcached_return_t (\*memcached_trigger_key)(memcached_st \*ptr, char \*key, size_t key_length, memcached_result_st \*result);
+The prototype for this is:
+memcached_return_t (\*memcached_trigger_key)(memcached_st \*ptr, char \*key, size_t key_length, memcached_result_st \*result);
  
 
 

=== modified file 'docs/memcached_delete.rst'
--- docs/memcached_delete.rst	2011-04-14 04:27:08 +0000
+++ docs/memcached_delete.rst	2011-04-18 19:22:31 +0000
@@ -25,8 +25,8 @@
 find the given value.
 
 Expiration works by placing the item into a delete queue, which means that
-it won't possible to retrieve it by the "get" command, but "add" and 
-"replace" command with this key will also fail (the "set" command will 
+it won't be possible to retrieve it by the "get" command. The "add" and 
+"replace" commands with this key will also fail (the "set" command will 
 succeed, however). After the time passes, the item is finally deleted from server memory.
 
 Please note the the Danga memcached server removed tests for expiration in

=== modified file 'docs/memcached_dump.rst'
--- docs/memcached_dump.rst	2011-04-14 04:27:08 +0000
+++ docs/memcached_dump.rst	2011-04-18 19:22:31 +0000
@@ -42,12 +42,12 @@
 -----------
 
 
-memcached_dump() is used to get a list of keys found  memcached(1) servers.
+memcached_dump() is used to get a list of keys found in memcached(1) servers.
 Because memcached(1) does not guarentee to dump all keys you can not assume
 you have fetched all keys from the server. The function takes an array
 of callbacks that it will use to execute on keys as they are found.
 
-Currently the binar protocol is not testsed.
+Currently the binary protocol is not testsed.
 
 
 ------

=== modified file 'docs/memcached_get.rst'
--- docs/memcached_get.rst	2011-04-14 04:27:08 +0000
+++ docs/memcached_get.rst	2011-04-18 19:22:31 +0000
@@ -65,7 +65,7 @@
 upon success and NULL will be returned on failure. MEMCACHD_END is returned
 by the \*error value when all objects that have been found are returned.
 The final value upon MEMCACHED_END is null. Values returned by
-memcached_fetch() musted be free'ed by the caller. memcached_fetch() will
+memcached_fetch() must be freed by the caller. memcached_fetch() will
 be DEPRECATED in the near future, memcached_fetch_result() should be used
 instead.
 
@@ -89,7 +89,7 @@
 similar to memcached_mget(), but it may trigger the supplied callbacks
 with result sets while sending out the queries. If you try to perform
 a really large multiget with memcached_mget() you may encounter a
-deadlock in the OS kernel (we fail to write data to the socket because
+deadlock in the OS kernel (it will fail to write data to the socket because
 the input buffer is full). memcached_mget_execute() solves this
 problem by processing some of the results before continuing sending
 out requests. Please note that this function is only available in the
@@ -100,9 +100,9 @@
 a master key that is used for determining which server an object was stored
 if key partitioning was used for storage.
 
-All of the above functions are not testsed when the \ ``MEMCACHED_BEHAVIOR_USE_UDP``\ 
+All of the above functions are not tested when the \ ``MEMCACHED_BEHAVIOR_USE_UDP``\ 
 has been set. Executing any of these functions with this behavior on will result in
-\ ``MEMCACHED_NOT_SUPPORTED``\  being returned or, for those functions which do not return
+\ ``MEMCACHED_NOT_SUPPORTED``\  being returned, or for those functions which do not return
 a \ ``memcached_return_t``\ , the error function parameter will be set to
 \ ``MEMCACHED_NOT_SUPPORTED``\ .
 

=== modified file 'docs/memcached_memory_allocators.rst'
--- docs/memcached_memory_allocators.rst	2011-04-14 04:27:08 +0000
+++ docs/memcached_memory_allocators.rst	2011-04-18 19:22:31 +0000
@@ -45,7 +45,7 @@
 -----------
 
 
-libmemcached(3) allows you to specify your own memory allocators optimized
+libmemcached(3) allows you to specify your own memory allocators, optimized
 for your application. This enables libmemcached to be used inside of applications that have their own malloc implementation.
 
 memcached_set_memory_allocators() is used to set the memory allocators used

=== modified file 'docs/memcached_result_st.rst'
--- docs/memcached_result_st.rst	2011-04-14 04:27:08 +0000
+++ docs/memcached_result_st.rst	2011-04-18 19:22:31 +0000
@@ -59,9 +59,9 @@
 
 libmemcached(3) can optionally return a memcached_result_st which acts as a
 result object. The result objects have added benefits over the character
-pointer returns in that they are forward compatible with new return items
+pointer returns, in that they are forward compatible with new return items
 that future memcached servers may implement (the best current example of
-this is the CAS return item). The structures can also be reused which will
+this is the CAS return item). The structures can also be reused, which will
 save on calls to malloc(3). It is suggested that you use result objects over
 char \* return functions.
 
@@ -72,7 +72,7 @@
 memcached_result_st or will initialize a structure passed to it.
 
 memcached_result_free() will deallocate any memory attached to the
-structure. If the structure was also alloacted, it will deallocate it.
+structure. If the structure was also allocated, it will deallocate it.
 
 memcached_result_key_value() returns the key value associated with the
 current result object.
@@ -91,7 +91,7 @@
 
 memcached_result_cas() returns the cas associated with the
 current result object. This value will only be available if the server
-testss it.
+tests it.
 
 memcached_result_set_value() takes a byte array and a size and sets
 the result to this value. This function is used for trigger responses.

=== modified file 'docs/memcached_sasl.rst'
--- docs/memcached_sasl.rst	2011-04-09 00:46:34 +0000
+++ docs/memcached_sasl.rst	2011-04-18 19:22:31 +0000
@@ -44,7 +44,7 @@
 Please note that SASL requires the memcached binary protocol, and you have
 to specify the callbacks before you connect to the server.
 
-memcached_set_sasl_auth_data() is a helper function for you defining
+memcached_set_sasl_auth_data() is a helper function defining
 the basic functionality for you, but it will store the username and password
 in memory. If you choose to use this method you have to call
 memcached_destroy_sasl_auth_data before calling memcached_free to avoid

=== modified file 'docs/memcached_set.rst'
--- docs/memcached_set.rst	2011-04-14 04:27:08 +0000
+++ docs/memcached_set.rst	2011-04-18 19:22:31 +0000
@@ -49,8 +49,8 @@
 memcached_set(), memcached_add(), and memcached_replace() are all used to
 store information on the server. All methods take a key, and its length to
 store the object. Keys are currently limited to 250 characters by the
-memcached(1) server. You must also supply a value and a length. Optionally you
-may tests an expiration time for the object and a 16 byte value (it is
+memcached(1) server. You must supply both a value and a length. Optionally you
+may test an expiration time for the object and a 16 byte value (it is
 meant to be used as a bitmap).
 
 memcached_set() will write an object to the server. If an object already
@@ -87,12 +87,12 @@
 the fastest way to store data on the server.
 
 All of the above functions are testsed with the \ ``MEMCACHED_BEHAVIOR_USE_UDP``\ 
-behavior enabled. But when using these operations with this behavior on, there 
+behavior enabled. However, when using these operations with this behavior on, there 
 are limits to the size of the payload being sent to the server.  The reason for 
-these limits is that the Memcahed Server does not allow multi-datagram requests
+these limits is that the Memcached Server does not allow multi-datagram requests
 and the current server implementation sets a datagram size to 1400 bytes. Due 
 to protocol overhead, the actual limit of the user supplied data is less than 
-1400 bytes and depends on the protocol in use as well as the operation being 
+1400 bytes and depends on the protocol in use as, well as the operation being 
 executed. When running with the binary protocol, \ `` MEMCACHED_BEHAVIOR_BINARY_PROTOCOL``\ , 
 the size of the key,value, flags and expiry combined may not exceed 1368 bytes. 
 When running with the ASCII protocol, the exact limit fluctuates depending on 

=== modified file 'docs/memcached_version.rst'
--- docs/memcached_version.rst	2011-04-14 04:27:08 +0000
+++ docs/memcached_version.rst	2011-04-18 19:22:31 +0000
@@ -39,7 +39,7 @@
 
 
 memcached_lib_version() is used to return a simple version string representing
-the libmemcached version (version of the client library, not server)
+the libmemcached version (client library version, not server version)
 
 memcached_version() is used to set the major, minor, and micro versions of each
 memcached server being used by the memcached_st connection structure. It returns the 

=== modified file 'docs/memcapable.rst'
--- docs/memcapable.rst	2011-04-14 04:27:08 +0000
+++ docs/memcapable.rst	2011-04-18 19:22:31 +0000
@@ -16,29 +16,29 @@
 
 .. option:: -h hostname
  
- Specify the hostname to connect to. The default is \ *localhost*\ 
+Specify the hostname to connect to. The default is \ *localhost*\ 
 
 .. option:: -p port
  
- Specify the port number to connect to. The default is \ *11211*\ 
+Specify the port number to connect to. The default is \ *11211*\ 
  
 
 
 .. option:: -c
  
- Generate a coredump when it detects an error from the server.
+Generate a coredump when it detects an error from the server.
  
 
 
 .. option:: -v
  
-  Print out the comparison when it detects an error from the server.
+Print out the comparison when it detects an error from the server.
  
 
 
 .. option:: -t n
  
- Set the timeout from an IO operation to/from the server to \ *n*\  seconds.
+Set the timeout from an IO operation to/from the server to \ *n*\  seconds.
  
 -----------
 DESCRIPTION

=== modified file 'docs/memcp.rst'
--- docs/memcp.rst	2011-04-14 04:27:08 +0000
+++ docs/memcp.rst	2011-04-18 19:22:31 +0000
@@ -26,11 +26,10 @@
 It is similar to the standard UNIX cp(1) command.
 
 The key names will be the names of the files,
-without any directory path part.
+without any directory path.
 
 You can specify servers via the \ **--servers**\  option or via the
-environment variable \ ``MEMCACHED_SERVERS``\ . If you specify neither of
-these, the final value in the command line list is the name of a
+environment variable \ ``MEMCACHED_SERVERS``\. If you do not specify either these, the final value in the command line list is the name of a
 server(s).
 
 For a full list of operations run the tool with the \ **--help**\  option.

=== modified file 'docs/memdump.rst'
--- docs/memdump.rst	2011-04-14 04:27:08 +0000
+++ docs/memdump.rst	2011-04-18 19:22:31 +0000
@@ -21,7 +21,7 @@
 -----------
 
 
-\ **memdump**\  currently dumps a list of "keys" from all servers that 
+\ **memdump**\  dumps a list of "keys" from all servers that 
 it is told to fetch from. Because memcached does not guarentee to
 provide all keys it is not possible to get a complete "dump".
 

=== modified file 'docs/memerror.rst'
--- docs/memerror.rst	2011-04-14 04:27:08 +0000
+++ docs/memerror.rst	2011-04-18 19:22:31 +0000
@@ -3,7 +3,7 @@
 ==============================================
 
 
-Translate a memcached error code to a string
+Translates a memcached error code into a string
 
 
 --------
@@ -21,7 +21,7 @@
 -----------
 
 
-\ **memerror**\  translate an error code from libmemcached(3) to  a human
+\ **memerror**\  translate an error code from libmemcached(3) into a human
 readable string.
 
 For a full list of operations run the tool with the \ **--help**\  option.

=== modified file 'docs/memflush.rst'
--- docs/memflush.rst	2011-04-14 04:27:08 +0000
+++ docs/memflush.rst	2011-04-18 19:22:31 +0000
@@ -22,7 +22,7 @@
 
 
 \ **memflush**\  resets the contents of memcached(1) servers.
-This means all data in these servers will be deleted.
+This means that all data in the specified servers will be deleted.
 
 You can specify servers via the \ **--servers**\  option or via the
 environment variable \ ``MEMCACHED_SERVERS``\ .

=== modified file 'docs/memslap.rst'
--- docs/memslap.rst	2011-04-11 05:22:20 +0000
+++ docs/memslap.rst	2011-04-18 19:22:31 +0000
@@ -20,12 +20,9 @@
 
 
 \ **memslap**\  is a load generation and benchmark tool for memcached(1)
-servers. It generates configurable workload such as threads, concurrencies, connections,
-run time, overwrite, miss rate, key size, value size, get/set proportion,
-expected throughput, and so on. 
+servers. It generates configurable workload such as threads, concurrencies, connections, run time, overwrite, miss rate, key size, value size, get/set proportion, expected throughput, and so on. 
 
-You can specify servers via the \ **--servers**\  option or via the
-environment variable \ ``MEMCACHED_SERVERS``\ .
+You can specify servers via the \ **--servers**\  option or via the environment variable \ ``MEMCACHED_SERVERS``\ .
 
 
 --------