Fix javadocs

Author: beothorn

src/main/java/webGrude/OkHttpBrowser.java

@@ -47,6 +47,13 @@ public class OkHttpBrowser implements LinkVisitor {
     private OkHttpClient client;
     private final Webgrude webgrude = new Webgrude();
 
+    /**
+     * Creates a new instance of OkHttpBrowser using the default Webgrude and OkHttpClient.
+     */
+    public OkHttpBrowser() {
+        // Default constructor
+    }
+
     /**
      * Loads content from url from the Page annotation on pageClass onto an instance of pageClass.
      *

src/main/java/webGrude/Webgrude.java

@@ -24,25 +24,45 @@
 import java.util.regex.Matcher;
 import java.util.regex.Pattern;
 
+/**
+ * Core class responsible for mapping HTML or XML content to Java objects annotated with Webgrude annotations.
+ * <p>
+ * Use this to parse a page's contents and populate annotated fields with selected data.
+ */
 public class Webgrude {
 
+
+    /**
+     * Synthetic root tag used when parsing XML and HTML fragments so it always have a root.
+     */
     public static final String ROOT_FAKE = "rootFake";
+
     private final boolean debug;
 
-    public Webgrude(){
+
+    /**
+     * Creates a new Webgrude instance.
+     */
+    public Webgrude() {
         debug = false;
     }
 
-    public Webgrude(boolean debug){
+    /**
+     * Creates a new Webgrude instance.
+     *
+     * @param debug whether to enable debug logging
+     */
+    public Webgrude(boolean debug) {
         this.debug = debug;
     }
 
-    /***
-     * Maps a Html string to a class with {@literal @}Selector annotations
-     * @param pageContents
-     * @param pageClass
-     * @return the page instance
-     * @param <T> The page class
+    /**
+     * Maps an HTML string to a class with {@literal @}Selector annotations.
+     *
+     * @param pageContents the HTML content to be parsed
+     * @param pageClass    the class with annotated fields to populate
+     * @param <T>          the type of the page class
+     * @return an instance of the page class populated with data from the HTML
      */
     public <T> T map(
             final String pageContents,
@@ -52,13 +72,14 @@ public <T> T map(
         return map(pageContents, pageClass, url);
     }
 
-    /***
-     * Maps a Html string to a class with {@literal @}Selector annotations
-     * @param pageContents
-     * @param pageClass
-     * @param baseUrl Used to populate links with the full href
-     * @return the page instance
-     * @param <T> The page class
+    /**
+     * Maps an HTML string to a class with {@literal @}Selector annotations.
+     *
+     * @param pageContents the HTML content to be parsed
+     * @param pageClass    the class with annotated fields to populate
+     * @param baseUrl      base URL used to resolve relative links
+     * @param <T>          the type of the page class
+     * @return an instance of the page class populated with data from the HTML
      */
     public <T> T map(
         final String pageContents,
@@ -405,6 +426,12 @@ private static String encodeOrThrow(final String p) {
         return URLEncoder.encode(p, StandardCharsets.UTF_8);
     }
 
+    /**
+     * Checks whether the provided class is a type natively supported by Webgrude (String, Integer, Float, etc.).
+     *
+     * @param c the class to check
+     * @return true if the class is known and directly mappable, false otherwise
+     */
     public boolean typeIsKnown(final Class c) {
         return c.equals(String.class) ||
                 c.equals(Integer.class) || c.getSimpleName().equals("int") ||

src/main/java/webGrude/http/GetException.java

@@ -1,14 +1,26 @@
 package webGrude.http;
 
-
+/**
+ * Exception thrown when an error occurs during an HTTP GET operation.
+ */
 public class GetException extends RuntimeException {
 
+    /**
+     * Constructs a new GetException with a specified cause and the resource that was being fetched.
+     *
+     * @param e the underlying exception that caused the failure
+     * @param get the resource being fetched when the error occurred
+     */
     public GetException(Exception e, String get) {
         super("Error while getting " + get, e);
     }
 
+    /**
+     * Constructs a new GetException with a message describing the resource that failed to be fetched.
+     *
+     * @param error description of the error or resource
+     */
     public GetException(String error) {
         super("Error while getting " + error);
     }
-
-}
+}

src/main/java/webGrude/http/LinkVisitor.java

@@ -1,5 +1,18 @@
 package webGrude.http;
 
+/**
+ * An interface for visiting links and retrieving their content.
+ * <p>
+ * Implementations of this interface define how to fetch the content of a given URL,
+ * it can be an http fetch or a custom way.
+ */
 public interface LinkVisitor {
+
+    /**
+     * Visits the provided URL and returns its contents as a string.
+     *
+     * @param href the URL to visit
+     * @return the contents of the page at the given URL
+     */
     String visitLink(final String href);
 }

src/main/java/webGrude/mapping/IncompatibleTypes.java

@@ -1,29 +1,36 @@
 package webGrude.mapping;
 
 import org.jsoup.nodes.Element;
-
 import webGrude.mapping.annotations.Selector;
 
+/**
+ * Exception thrown when a selected node cannot be mapped to the expected field type,
+ * indicating incompatible types between the HTML element and the annotated field.
+ */
 public class IncompatibleTypes extends Exception {
 
     /**
+     * Constructs a new IncompatibleTypes exception with details about the mapping failure.
      *
+     * @param newInstance the object instance being populated
+     * @param selectedNode the HTML element selected during parsing
+     * @param selectorAnnotation the annotation used to select the element
+     * @param fieldClass the expected type of the field
+     * @param e the underlying exception that caused the type incompatibility
      */
-    private static final long serialVersionUID = 751653411036904421L;
-
     public IncompatibleTypes(
-        final Object newInstance,
-        final Element selectedNode,
-        final Selector selectorAnnotation,
-        final Class<?> fieldClass,
-        final Exception e
+            final Object newInstance,
+            final Element selectedNode,
+            final Selector selectorAnnotation,
+            final Class<?> fieldClass,
+            final Exception e
     ){
         super(
-            "{\n"+
-                "\tInstance type: "+newInstance.getClass().getName()+
-                "\n\tField Type: "+fieldClass+
-                "\n\tNode: "+selectedNode+
-                "\n\tAnnotation: "+selectorAnnotation+
-            "\n}",e);
+                "{\n"+
+                        "\tInstance type: "+newInstance.getClass().getName()+
+                        "\n\tField Type: "+fieldClass+
+                        "\n\tNode: "+selectedNode+
+                        "\n\tAnnotation: "+selectorAnnotation+
+                        "\n}", e);
     }
-}
+}

src/main/java/webGrude/mapping/TooManyResultsException.java

@@ -2,16 +2,30 @@
 
 import org.jsoup.select.Elements;
 
+/**
+ * Thrown when a CSS selector matches more than one element but the corresponding field
+ * is not a collection type.
+ * <p>
+ * This exception is intended to alert the developer that a single-value field (e.g., {@code String})
+ * is annotated with a selector that yields multiple elements in the HTML document.
+ * In such cases, the field should be defined as a {@code List} of the appropriate type.
+ */
 public class TooManyResultsException extends RuntimeException {
 
+    /**
+     * Constructs a new TooManyResultsException with details about the selector and matched elements.
+     *
+     * @param cssQuery the CSS selector used to find the elements
+     * @param size     the number of elements matched
+     * @param elements the matched elements
+     */
     public TooManyResultsException(
-        final String cssQuery,
-        final int size,
-        final Elements elements
+            final String cssQuery,
+            final int size,
+            final Elements elements
     ) {
         super("The query '" + cssQuery + "' should return one result but returned "
-                    + size + ". For more than one result a list should be used as the field type."
-                    + elements);
+                + size + ". For more than one result a list should be used as the field type."
+                + elements);
     }
-
-}
+}

src/main/java/webGrude/mapping/annotations/Selector.java

@@ -3,59 +3,29 @@
 import webGrude.OkHttpBrowser;
 
 import java.lang.annotation.ElementType;
-import java.lang.annotation.Repeatable;
 import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
 /**
- * Annotates a field to be mapped using a css selector.
+ * Annotates a field to be mapped using a CSS selector.
  * <p>
- * A field annotated with this will receive the value corresponding to it's css
+ * A field annotated with this will receive the value corresponding to its CSS
  * selector when mapped.
- * The field can be any of the following types (or its primitive):
+ * The field can be one of the following types (or its primitive counterpart):
  * <ul>
- * <li>String</li>
- * <li>Float</li>
- * <li>Integer</li>
- * <li>Boolean</li>
- * <li>webGrude.mapping.elements.Link</li>
- * <li>org.jsoup.nodes.Element</li>
+ *   <li>String</li>
+ *   <li>Float</li>
+ *   <li>Integer</li>
+ *   <li>Boolean</li>
+ *   <li>{@code webGrude.mapping.elements.Link}</li>
+ *   <li>{@code org.jsoup.nodes.Element}</li>
  * </ul>
- * Or a List of any of these types.<br>
- * You can also set the field as an attribute value instead of it's text using
- * the attr annotation value. html and outerHtml are also valid values for attr.
- * For example:
+ * Or a {@code List} of any of these types.
  * <p>
- * A field mapping a link with id foo
- * </p>
- * <pre>
- * {@code @Selector("#foo") String fooText;}
- * </pre>
- * <p>
- * A field mapping a link with id foo but receiving the href value
- * </p>
- * <pre>
- * {@code @Selector(value = "#foo", attr="href") String fooText;}
- * </pre>
- * <p>
- * A field mapping a link with id foo but receiving the href value
- * </p>
- * <pre>
- * {@code @Selector(value = "#foo", attr="href") String fooText;}
- * </pre>
- * <p>
- * A field mapping a the inner html code of a link with id foo
- * </p>
- * <pre>
- * {@code @Selector(value = "#foo", attr="html") String fooHtml;}
- * </pre>
- * <p>
- * A field mapping a the outer html code of a link with id foo
- * </p>
- * <pre>
- * {@code @Selector(value = "#foo", attr="outerHtml") String fooOuterHtml;}
- * </pre>
+ * You can also extract an attribute's value instead of the element's text using
+ * the {@code attr} attribute. Special values for {@code attr} include:
+ * {@code "html"} (inner HTML) and {@code "outerHtml"} (entire HTML of the element).
  *
  * @author beothorn
  * @see webGrude.mapping.annotations.Page
@@ -65,9 +35,42 @@
 @Retention(RetentionPolicy.RUNTIME)
 @Target({ElementType.FIELD})
 public @interface Selector {
+
+    /**
+     * The CSS selector used to locate the element(s).
+     *
+     * @return the CSS selector string
+     */
     String value();
+
+    /**
+     * The attribute to extract from the selected element.
+     * If empty, the text content is used.
+     * Special values include "html" and "outerHtml".
+     *
+     * @return the attribute name or empty for text content
+     */
     String attr() default "";
+
+    /**
+     * A formatting pattern (e.g., for dates or numbers) to apply when mapping the value.
+     *
+     * @return the format string
+     */
     String format() default "";
+
+    /**
+     * The locale to use for formatting and parsing.
+     * Should be in the form of a language tag, e.g., "en-US".
+     *
+     * @return the locale string
+     */
     String locale() default "";
+
+    /**
+     * The default value to assign to the field if the selector does not match anything.
+     *
+     * @return the default value
+     */
     String defValue() default "";
 }

src/main/java/webGrude/mapping/annotations/XPath.java

@@ -5,8 +5,19 @@
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
+/**
+ * Indicates that a field should be mapped using an XPath expression instead of a CSS selector.
+ * <p>
+ * This annotation can be used in combination with {@code @Selector} to enable XPath-based node selection.
+ */
 @Retention(RetentionPolicy.RUNTIME)
 @Target({ElementType.FIELD})
-public @interface XPath{
+public @interface XPath {
+
+    /**
+     * The XPath expression to use for selecting the element(s).
+     *
+     * @return the XPath query string
+     */
     String value() default "";
 }