added some javadoc to JSONPointer

erosb · erosb · commit 5223aadd67df · 2016-04-27T00:10:06.000+02:00
diff --git a/JSONPointer.java b/JSONPointer.java
@@ -8,10 +8,22 @@
 import java.util.ArrayList;
 import java.util.List;
 
+/**
+ * A JSON Pointer is a simple query language defined for JSON documents by
+ * <a href="https://tools.ietf.org/html/rfc6901">RFC 6901</a>. 
+ */
 public class JSONPointer {
 
     private List<String> refTokens;
 
+    /**
+     * Pre-parses and initializes a new {@code JSONPointer} instance. If you want to
+     * evaluate the same JSON Pointer on different JSON documents then it is recommended
+     * to keep the {@code JSONPointer} instances due to performance considerations.
+     * 
+     * @param pointer the JSON String or URI Fragment representation of the JSON pointer.
+     * @throws IllegalArgumentException if {@code pointer} is not a valid JSON pointer
+     */
     public JSONPointer(String pointer) {
         if (pointer == null) {
             throw new NullPointerException("pointer cannot be null");
@@ -44,6 +56,16 @@ private String unescape(String token) {
                 .replace("\\\\", "\\");
     }
 
+    /**
+     * Evaluates this JSON Pointer on the given {@code document}. The {@code document}
+     * is usually a {@link JSONObject} or a {@link JSONArray} instance, but the empty
+     * JSON Pointer ({@code ""}) can be evaluated on any JSON values and in such case the
+     * returned value will be {@code document} itself. 
+     * 
+     * @param document the JSON document which should be the subject of querying.
+     * @return the result of the evaluation
+     * @throws JSONPointerException if an error occurs during evaluation
+     */
     public Object queryFrom(Object document) {
         if (refTokens.isEmpty()) {
             return document;
