   @unescape: (segment) ->
     segment.replace(/~1/g, '/').replace(/~0/g, '~')
 
+  ###
+  # Un-Escapes the given path fragment segment, reversing the actions of `.escapeFragment`.
+  #
+  # Notably, the string is URI decoded and then `'~1'`'s are replaced with `'/'` and `'~0'`'s are replaced with `'~'`.
+  #
+  # @param {string} segment
+  # @returns {string}
+  ###
   @unescapeFragment: (segment) ->
     JsonPointer.unescape(decodeURIComponent(segment))
 
+  ###
+  # Returns true iff `str` is a valid json pointer value
+  #
+  # @param {string} str
+  # @returns {Boolean}
+  ###
   @isPointer: (str) ->
     switch str.charAt(0)
       when '' then return true

  @escape: (segment) ->
    segment.replace(/~/g, '~0').replace(/\//g, '~1')

  @escapeFragment: (segment) ->
    encodeURIComponent(JsonPointer.escape(segment))


      else
        throw new JsonPointerError("Invalid JSON pointer: #{str}")

  ###
  # Parses a json-pointer, as desribed by RFC901, into an array of path segments.
  #
  # @throws {JsonPointerError} for invalid json-pointers.
  #
  # @param {string} str
  # @returns {string[]}
  ###
  @parsePointer: (str) ->
    switch str.charAt(0)
      when '' then return []
      when '/' then return str.substring(1).split('/').map(JsonPointer.unescape)
      else throw new JsonPointerError("Invalid JSON pointer: #{str}")

  ###
  # Parses a json fragment pointer, as desribed by RFC901, into an array of path segments.
  #
  # @throws {JsonPointerError} for invalid json-pointers.
  #
  # @param {string} str
  # @returns {string[]}
  ###
  @parseFragment: (str) ->
    switch str.substring(0, 2)
      when '#' then return []
