docs: m2r BUGS.md issues.rst

Author: m6w6

BUGS.md

@@ -39,3 +39,20 @@ specify whether `MGET`s/`GET`s should read from a random server with
 delete the key from all replicas.
 
 The binary protocol is required and any other command is unaffected.
+
+### TLS/SSL
+
+libmemcached does not support TLS/SSL, yet. 
+See [github issue #37](https://github.com/awesomized/libmemcached/issues/37).
+
+
+### Coroutines and event loops 
+
+libmemcached does not support explicit asynchronous usage, yet.
+See [github issue #54](https://github.com/awesomized/libmemcached/issues/54).
+
+
+### META protocol
+
+libmemcached deos not support memcached's META protocol, yet.
+See [github issue #121](https://github.com/awesomized/libmemcached/issues/121).

docs/source/CMakeLists.txt

@@ -1,25 +1,34 @@
 find_program(M2R NAMES m2r m2r-3)
 
+function(DefaultRstPath MDFILE RSTFILE_VAR)
+    string(REGEX REPLACE "\\.md$" ".rst" FILEPATH ${MDFILE})
+    get_filename_component(FILENAME ${FILEPATH} NAME)
+    set(${RSTFILE_VAR} "${CMAKE_CURRENT_SOURCE_DIR}/${FILENAME}" PARENT_SCOPE)
+endfunction()
+
+function(UpdateRstFromMd RSTFILE MDFILE)
+    if(${MDFILE} IS_NEWER_THAN ${RSTFILE})
+        message("--   Processing ${MDFILE} ...")
+        execute_process(
+                COMMAND ${M2R} --overwrite --parse-relative-links ${MDFILE}
+                RESULTS_VARIABLE M2R_STATUS
+        )
+        if(M2R_STATUS)
+            message("     Failed to update ${RSTFILE}: ${M2R_STATUS}")
+        else()
+            string(REGEX REPLACE "\\.md$" ".rst" FILEPATH ${MDFILE})
+            file(RENAME ${FILEPATH} ${RSTFILE} )
+            message("     Updated ${RSTFILE}: OK")
+        endif()
+    endif()
+endfunction()
+
 if(M2R)
+    message("-- Checking ChangeLogs, BUGS, etc...")
     file(GLOB CHANGELOGS "${CMAKE_SOURCE_DIR}/ChangeLog-*.md")
-    message("-- Checking ChangeLogs ...")
     foreach(CHANGELOG IN LISTS CHANGELOGS)
-        string(REGEX REPLACE "\\.md$" ".rst" FILEPATH ${CHANGELOG})
-        get_filename_component(FILENAME ${FILEPATH} NAME)
-
-        set(RESTFILE "${CMAKE_CURRENT_SOURCE_DIR}/${FILENAME}")
-        if(${CHANGELOG} IS_NEWER_THAN ${RESTFILE})
-            message("--   Processing ${CHANGELOG} ...")
-            execute_process(
-                    COMMAND ${M2R} --overwrite --parse-relative-links ${CHANGELOG}
-                    RESULTS_VARIABLE M2R_STATUS
-            )
-            if(M2R_STATUS)
-                message("     Failed to update ${RESTFILE}: ${M2R_STATUS}")
-            else()
-                file(RENAME ${FILEPATH} ${RESTFILE} )
-                message("     Updated ${RESTFILE}: OK")
-            endif()
-        endif()
+        DefaultRstPath(${CHANGELOG} RESTFILE)
+        UpdateRstFromMd(${RESTFILE} ${CHANGELOG})
     endforeach()
+    UpdateRstFromMd(issues.rst "${CMAKE_SOURCE_DIR}/BUGS.md")
 endif()

docs/source/index.rst

@@ -20,6 +20,7 @@ memory usage, thread safe, and provide full access to server side methods.
     :maxdepth: 1
 
     changelogs
+    Known issues <issues>
     copyright
 
 Index

docs/source/issues.rst

@@ -0,0 +1,65 @@
+
+Bugs, Known Issues and Insufficiencies
+======================================
+
+libhashkit
+----------
+
+libhashkit is not usable for general purpose hashing, because it is geared to
+usage by libmemcached.
+
+MurMur
+^^^^^^
+
+Hashkit's MurMur/MurMur3 are limited to the lower 32 bits.
+
+crc32
+^^^^^
+
+Commit "\ `More Hashing methods <https://github.com/awesomized/libmemcached/commits/1207354f>`_\ "
+from October 2007 first released in v0.8, which main intention seems to have
+been to add FNV1 hash algos, changed the result of the crc32 hash to only its
+upper 16 bits sans MSB, without any additional comment.
+
+The implementations referred to in the file header (Postgres and BSD)
+do not exhibit this behavior.
+
+A `bug report <https://bugs.launchpad.net/libmemcached/+bug/604178>`_ was
+filed three years later on launchpad, which was marked ``Won't fix`` with
+the comment that it was for compatibility with other "drivers", which
+supposedly refers to other memcached client libraries.
+
+libmemcached
+------------
+
+Replication
+^^^^^^^^^^^
+
+This is a somewhat badly named feature, because it **does not** provide
+any of the guaranties one would expect from a proper replication.
+
+One can set the intended number of additional servers where data should
+be stored with the behavior ``MEMCACHED_BEHAVIOR_NUMBER_OF_REPLICAS`` and
+specify whether ``MGET``\ s/\ ``GET``\ s should read from a random server with 
+``MEMCACHED_BEHAVIOR_RANDOMIZE_REPLICA_READ``. ``DELETE``\ s will try to 
+delete the key from all replicas.
+
+The binary protocol is required and any other command is unaffected.
+
+TLS/SSL
+^^^^^^^
+
+libmemcached does not support TLS/SSL, yet. 
+See `github issue #37 <https://github.com/awesomized/libmemcached/issues/37>`_.
+
+Coroutines and event loops
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+libmemcached does not support explicit asynchronous usage, yet.
+See `github issue #54 <https://github.com/awesomized/libmemcached/issues/54>`_.
+
+META protocol
+^^^^^^^^^^^^^
+
+libmemcached deos not support memcached's META protocol, yet.
+See `github issue #121 <https://github.com/awesomized/libmemcached/issues/121>`_.