                                         ((eq k json-null)  "{}"))))
     (json-encode obj)))
 
+;; This defines 'ycmd-hmac-function which we use to combine an HMAC
+;; key and message contents.
 (define-hmac-function ycmd-hmac-function
   (lambda (x) (secure-hash 'sha256 x nil nil 1))
   64 64)
 
 (defun ycmd-options-contents (hmac-secret)
+  "Return a struct which can be JSON encoded into a file to
+create a ycmd options file.
+
+When we start a new ycmd server, it needs an options file. It
+reads this file and then deletes it since it contains a secret
+key. So we need to generate a new options file for each ycmd
+instance. This function effectively produces the contents of that
+file."
   (let ((hmac-secret (base64-encode-string hmac-secret)))
     `((filetype_blacklist (vimwiki . 1) (mail . 1) (qf . 1) (tagbar . 1) (unite . 1) (infolog . 1) (notes . 1) (text . 1) (pandoc . 1) (markdown . 1))
       (auto_start_csharp_server . 1)

(require 'json)
(require 'request)

(defcustom ycmd-host "127.0.0.1"
  "The host on which the ycmd server is running."
  :type '(string)

  defconst. It is not, however, treated as a constant by this
  code. This value gets set in ycmd-open.")

(defconst ycmd-server-process "ycmd-server"
  "The emacs name of the server process. This is used by
  functions like start-process, get-process, and delete-process.")

(defun ycmd-generate-hmac-secret ()
  "Generate a new, random 16-byte HMAC secret key."
  (let ((result '()))
    (dotimes (x 16 result)
      (setq result (cons (byte-to-string (random 256)) result)))
    (apply 'concat result)))

(defun ycmd-json-encode (obj)
  "A version of json-encode that uses {} instead of null for nil
