Better Javadocs

pom.xml

@@ -33,6 +33,16 @@
           </execution>
         </executions>
   		</plugin>
+  		<plugin>
+  			<groupId>org.apache.maven.plugins</groupId>
+  			<artifactId>maven-javadoc-plugin</artifactId>
+  			<version>2.7</version>
+  			<configuration>
+  				<excludePackageNames>de.monoid.web.*</excludePackageNames>
+  				<show>public</show>
+  				<charset>utf-8</charset>
+  			</configuration>
+  		</plugin>
   	</plugins>
   </build>
   <repositories>
@@ -61,11 +71,6 @@
   </dependencies>
   <reporting>
   	<plugins>
-  		<plugin>
-  			<groupId>de.monoid.apache.maven.plugin</groupId>
-  			<artifactId>maven-javadoc-plugin</artifactId>
-  			<version>2.7</version>
-  		</plugin>
   	</plugins>
   </reporting>
 </project>

src/main/java/de/monoid/web/AbstractResource.java

@@ -10,9 +10,9 @@
 
 /**
  * Abstract base class for all resource handlers you want to use with Resty.
- * Resource handlers aka content handlers hold the content returned from a
- * URLConnection
  * 
+ * It gives access to the underlying URLConnection and the current inputStream
+ *
  * @author beders
  * 
  */

src/main/java/de/monoid/web/Content.java

@@ -9,6 +9,8 @@
 
 /**
  * Class to encapsulate content being sent as payload of a POST request.
+ * You can use Resty.content(...) to create content objects. 
+ * 
  * 
  * @author beders
  *

src/main/java/de/monoid/web/FormContent.java

@@ -1,9 +1,9 @@
 package de.monoid.web;
 
-import java.io.IOException;
 import java.io.UnsupportedEncodingException;
 
 /** Encapsulates form-data sent to web services.
+ * Currently only application/x-www-form-urlencoded is supported.
  * 
  * @author beders
  *

src/main/java/de/monoid/web/JSONPathQuery.java

@@ -9,6 +9,21 @@
 import de.monoid.web.jp.javacc.JSONPathCompiler;
 import de.monoid.web.jp.javacc.ParseException;
 
+/** Create a path query for a JSON object. Usualy this is done by calling Resty.path(...)
+ * 
+ * A JSONPathQuery is similar to JsonPath or XPath in that you can create access paths into an JSON object.
+ * It uses dot '.' as a path separator and [] to access arrays. 
+ * The array index is either a number or an expression to evaluate for each object in the array. The first matching object is returned.
+ * I.e. <p>
+ * <code>store.book[price>7 && price<12.999].author</code>
+ * <p>
+ * In the example above the JSON object with a prive value between 7 and 12.999 is selected and the author returned.
+ * Boolean expressions are supported with && (and), || (or), ! (not). Values can be compared with =,<,>.
+ * 
+ * 
+ * @author beders
+ *
+ */
 public class JSONPathQuery extends PathQuery<JSONResource, Object> {
 	private JSONPathCompiler compiler;
 	private String expr;

src/main/java/de/monoid/web/JSONResource.java

@@ -8,9 +8,21 @@
 import de.monoid.json.JSONObject;
 import de.monoid.json.JSONTokener;
 
+/** A resource presentation in JSON format.
+ * You can  ask Resty to parse the JSON into a JSONObject, which is similar to the org.json.JSONObject and allows full access to the JSON.
+ * You can also access the JSON with a JSONPathQuery to extract only the parts you are interested in.
+ * @author beders
+ *
+ */
 public class JSONResource extends AbstractResource {
 	JSONObject json;
 
+	/** 
+	 * Parse and return JSON object. Parsing is done only once after which the inputStrem is at EOF.
+	 * @return the JSON object
+	 * @throws IOException
+	 * @throws JSONException
+	 */
 	public JSONObject object() throws IOException, JSONException {
 		if (json == null) {
 			json = unmarshal();
@@ -86,6 +98,11 @@ public XMLResource xml(JSONPathQuery path, Content content) throws Exception {
 	public Object get(String path) throws Exception {
 		return new JSONPathQuery(path).eval(this);
 	}
+
+	/** Gets the partial JSON object or attribute as specified in the path expression.*/
+	public Object get(JSONPathQuery aQuery) throws Exception {
+		return aQuery.eval(this);
+	}
 
 	@Override
 	String getAcceptedTypes() {

src/main/java/de/monoid/web/PathQuery.java

@@ -1,6 +1,8 @@
 package de.monoid.web;
 
-/** Abstraction for queries into complex datastructures.
+/** 
+ * Simple abstraction for queries into complex datastructures.
+ * Not really needed, but I like playing around with generics. :)
  * 
  * @author beders
  *

src/main/java/de/monoid/web/Resty.java

@@ -16,30 +16,33 @@
 import de.monoid.web.auth.RestyAuthenticator;
 
 /**
- * Resty is a small, convenient interface to talk to RESTful services. Its focus
- * is on simplicity and ease-of-use, often requiring only two lines of code to
- * access any web service. It supports chaining several requests which is very
- * useful in RESTful application employing HATEOS.
+ * Main class. Use me! Use me!
+ * Resty is a small, convenient interface to talk to RESTful services. 
  * 
  * Basic usage is very simple: Create a Resty instance, use authenticate methode
  * to add credentials, then call one of the content type specific methods. The
  * idea is that the method name will convey the expected content type you can
  * then operate on.
  * 
+ * A neat trick to save you typing is to use import static de.monoid.web.Resty.*;
+ * 
  * Here is an example on how to use the geonames web service. It retrieves the
  * json object (see json.org for details) and gets the name of a place from the
  * zip code:
- * 
+ * <pre>
  * <code>
 	Resty r = new Resty();
 	Object name = r.json("http://ws.geonames.org/postalCodeLookupJSON?postalcode=66780&country=DE").get("postalcodes[0].placeName");
 	assertEquals(name, "Rehlingen-Siersburg");
  * </code>
+ * </pre>
  * 
  * Resty supports complex path queries to navigate into a json object. This is
  * mainly used for extracting URIs to surf along a series of REST resources for
  * web services following the HATEOS paradigm.
  * 
+ * Resty objects are not re-entrant.
+ * 
  * @author beders
  *
  */
@@ -58,6 +61,9 @@ public class Resty {
 
 	protected String userAgent = DEFAULT_USER_AGENT;
 
+	/** Create a new instance without any options. 
+	 * Oh, ok, there are no options yet :)
+	 */
 	public Resty() {
 		// no options
 	}
@@ -81,7 +87,13 @@ public Resty() {
 	public void authenticate(URI aSite, String aLogin, char[] aPwd) {
 		rath.addSite(aSite, aLogin, aPwd);
 	}
-
+
+	/** @see Resty#authenticate(URI, String, char[])
+	 * 
+	 * @param string
+	 * @param aLogin
+	 * @param charArray
+	 */
 	public void authenticate(String string, String aLogin, char[] charArray) {
 		authenticate(URI.create(string), aLogin, charArray);
 	}
@@ -313,14 +325,19 @@ public static JSONPathQuery path(String string) {
 	/** Create an XPathQuery to extract data from an XML document. This is usually used to extract a URI and use it
 	 * in json|text|xml(XPathQuery...) methods.
 	 * In this case, your XPath must result in a String value, i.e. it can't just extract an Element.
-	 * @param anXPathExpression
+	 * @param anXPathExpression an XPath expression with result type String
 	 * @return the query
 	 * @throws XPathException
 	 */
 	public static XPathQuery xpath(String anXPathExpression) throws XPathException {
 		return new XPathQuery(anXPathExpression);
 	}
 
+	/** Create a content object from JSON. Use this to POST the content to a URL.
+	 * 
+	 * @param someJson the JSON to use
+	 * @return the content to send
+	 */
 	public static Content content(JSONObject someJson) {
 		Content c = null;
 		try {
@@ -330,6 +347,11 @@ public static Content content(JSONObject someJson) {
 		return c;
 	}
 
+	/** Create a content object from plain text. Use this to POST the content to a URL.
+	 * 
+	 * @param somePlainText the JSON to use
+	 * @return the content to send
+	 */
 	public static Content content(String somePlainText) {
 		Content c = null;
 		try {
@@ -349,6 +371,11 @@ public static FormContent form(String query) {
 		return fc;
 	}
 
+	/** Shortcut to URLEncoder.encode with UTF-8.
+	 * 
+	 * @param unencodedString the string to encode
+	 * @return the URL encoded string, safe to be used in URLs
+	 */
 	public static String enc(String unencodedString) {
 		try {
 			return URLEncoder.encode(unencodedString, "UTF-8");

src/main/java/de/monoid/web/TextResource.java

@@ -19,6 +19,9 @@ public class TextResource extends AbstractResource {
 	static final Pattern charsetPattern = Pattern.compile("charset=([^ ;]+);?");
 	protected String text;
 
+	/** Kinda obvious, but, yes, it parses the inputStream with the proper charset and returns the content as String
+	 * 
+	 */
 	@Override
 	public String toString() {
 		if (text == null && inputStream != null) {

src/main/java/de/monoid/web/XMLResource.java

@@ -13,9 +13,24 @@
 
 import de.monoid.json.JSONException;
 
+
+/** Resource presentation for an XML document. 
+ * You can access the XML as a DOM document. I know, DOM sucks, but you are free to change this class to support
+ * your favorite XML parser.
+ * 
+ * What is not so sucky is access to the XML via XPath with the convenient get(...) methods.
+ * 
+ * @author beders
+ *
+ */
 public class XMLResource extends TextResource {
 	protected Document document;
 
+	/** Return the DOM of the XML resource.
+	 * 
+	 * @return
+	 * @throws IOException
+	 */
 	public Document doc() throws IOException {
 		// if the stream has alread been read, use the text format
 		InputSource is;

src/main/java/de/monoid/web/XPathQuery.java

@@ -10,6 +10,13 @@
 import org.w3c.dom.Node;
 import org.w3c.dom.NodeList;
 
+/** PathQuery for XPath.
+ * Use this to access XMLResource objects.
+ * Many times you might want to use Resty.xpath(...) to create instances of this class.
+ * 
+ * @author beders
+ *
+ */
 public class XPathQuery extends PathQuery<XMLResource,NodeList> {
 	protected XPathExpression xPathExpression;
 
@@ -42,7 +49,15 @@ NodeList eval(XMLResource resource) throws Exception {
 		return retVal;
 	}
 
-	<T> T eval(XMLResource resource, Class<T>aReturnType) throws Exception {
+	/** Evaluate the XPath on an XMLResource and convert the result into aReturnType.
+	 * 
+	 * @param <T> the expected type of the result
+	 * @param resource
+	 * @param aReturnType 
+	 * @return
+	 * @throws Exception
+	 */
+	public <T> T eval(XMLResource resource, Class<T>aReturnType) throws Exception {
 		T retVal = (T) xPathExpression.evaluate(resource.doc(), getConstant(aReturnType));
 		return retVal;
 	}

target/javadoc-bundle-options/javadoc-options-javadoc-resources.xml

@@ -6,5 +6,8 @@
   <tagletArtifacts>
     <tagletArtifact />
   </tagletArtifacts>
+  <excludePackageNames>
+    <excludePackageName>de.monoid.web.*</excludePackageName>
+  </excludePackageNames>
   <javadocResourcesDirectory>src/main/javadoc</javadocResourcesDirectory>
 </javadocOptions>