Add some documentation.

Author: carlosame

README.md

@@ -5,6 +5,30 @@ projects.
 
 <br/>
 
+## Why the Web APIs project?
+
+[EchoSVG](https://github.com/css4j/echosvg) is a fork of Apache Batik, an SVG
+toolkit in the Java language. Both projects require Java bindings based on old
+versions of the SVG and SMIL DOM APIs.
+
+Apache Batik uses the `xml-apis-ext-1.3.04.jar` package, which is unsuitable for
+modular Java due to the fact that it also contains the SAC package which is found
+in other packages.
+
+This project offers separate packages for SVGOM and SMIL which aren't the exact
+ones shipped by `xml-apis-ext-1.3.04` but are compatible with both EchoSVG and
+Batik.
+
+The code is based on old Java bindings downloaded from the W3C, and several
+method signatures had to be modified so they matched the implementations in
+EchoSVG/Batik. Although it would have been easy to upgrade EchoSVG instead, that
+would have created problems in cases where both `xml-apis-ext-1.3.04.jar` and
+`svgom-api` or `smil-api` were found in the classpath or modulepath (which is
+conceivable if, for example, somebody is using EchoSVG and Apache FOP in the
+same project).
+
+<br/>
+
 ## Building from source
 
 ### Requirements
@@ -13,6 +37,7 @@ To build `web-apis` you need the following software installed:
 
 - The [Git version control system](https://git-scm.com/downloads) is required to
 obtain the sources. Any recent version should suffice.
+
 - Java 11 or later. You can install it from your favourite package manager or by
 downloading from [Adoptium](https://adoptium.net/).
 
@@ -34,7 +59,9 @@ or just `gradlew build` (without the `./`) on a Windows command prompt.
 ### Deploying to a Maven repository
 
 Use:
+
 - `gradlew build publishToMavenLocal` to install in your local Maven repository.
+
 - `gradlew publish` to deploy to a (generally remote) Maven repository.
 
 Before deploying to a remote Maven repository, please read the
@@ -50,6 +77,7 @@ to learn which properties you need to set (like `mavenReleaseRepoUrl`or
 
 If your Gradle project depends on any of the web-apis modules, you can use this
 project's own Maven repository in a `repositories` section of your build file:
+
 ```groovy
 repositories {
     maven {

smil-api/src/main/java/module-info.java

@@ -12,6 +12,19 @@
  * Later modifications:
  * Copyright (c) 2020-2021 Carlos Amengual
  */
+
+/**
+ * Synchronized Multimedia Integration Language (SMIL) Java binding.
+ * <p>
+ * This module contains the Java binding for a subset of an
+ * <a href="https://www.w3.org/TR/smil-boston-dom/java-binding.zip">old SMIL
+ * version</a>. It has been adapted for compatibility with the subset of SMIL
+ * that Apache Batik (and hence EchoSVG) uses (it uses the SMIL packages at the
+ * <a href=
+ * "http://archive.apache.org/dist/xml/commons/xml-commons-external-1.3.04-src.zip">{@code xml-apis-ext-1.3.04}</a>
+ * package).
+ * </p>
+ */
 module org.w3c.dom.smil {
 	exports org.w3c.dom.smil;
 

smil-api/src/main/java/org/w3c/dom/smil/ElementTimeControl.java

@@ -12,12 +12,54 @@
 
 package org.w3c.dom.smil;
 
+/**
+ * Control the behavior of an animated element.
+ */
 public interface ElementTimeControl {
+
+	/**
+	 * Creates a begin instance time for the current time which is added to the list
+	 * of begin instance times.
+	 * <p>
+	 * Note: modern versions of this method do not return any value.
+	 * </p>
+	 * 
+	 * @return {@code true}. The return value should be ignored.
+	 */
 	boolean beginElement();
 
+	/**
+	 * Creates a begin instance time for the current time plus or minus the passed
+	 * offset which is added to the list of begin instance times.
+	 * <p>
+	 * Note: modern versions of this method do not return any value.
+	 * </p>
+	 * 
+	 * @param offset the offset in seconds at which to begin the element.
+	 * @return {@code true}. The return value should be ignored.
+	 */
 	boolean beginElementAt(float offset);
 
+	/**
+	 * Creates an end instance time for the current time which is added to the list
+	 * of end instance times.
+	 * <p>
+	 * Note: modern versions of this method do not return any value.
+	 * </p>
+	 * 
+	 * @return {@code true}. The return value should be ignored.
+	 */
 	boolean endElement();
 
+	/**
+	 * Creates an end instance time for the current time plus or minus the passed
+	 * offset which is added to the list of end instance times.
+	 * <p>
+	 * Note: modern versions of this method do not return any value.
+	 * </p>
+	 * 
+	 * @param offset
+	 * @return {@code true}. The return value should be ignored.
+	 */
 	boolean endElementAt(float offset);
 }

smil-api/src/main/java/org/w3c/dom/smil/TimeEvent.java

@@ -15,10 +15,36 @@
 import org.w3c.dom.events.Event;
 import org.w3c.dom.views.AbstractView;
 
+/**
+ * Provides specific contextual information associated with Time events.
+ */
 public interface TimeEvent extends Event {
+
+	/**
+	 * Get the {@code AbstractView} from which this event was initialized.
+	 */
 	AbstractView getView();
 
+	/**
+	 * Get some detail information about the {@code Event}, depending on the type of
+	 * event.
+	 * 
+	 * @return a detail information about this event.
+	 */
 	int getDetail();
 
+	/**
+	 * Initialize this event.
+	 * <p>
+	 * This method may only be called before this event has been dispatched via the
+	 * {@code dispatchEvent} method, though it may be called multiple times during
+	 * that phase if necessary. If called multiple times, the final invocation takes
+	 * precedence.
+	 * </p>
+	 * 
+	 * @param typeArg   the event type.
+	 * @param viewArg   the event AbstractView.
+	 * @param detailArg the event's detail.
+	 */
 	void initTimeEvent(String typeArg, AbstractView viewArg, int detailArg);
 }

svgom-api/src/main/java/module-info.java

@@ -12,6 +12,25 @@
  * Later modifications:
  * Copyright (c) 2020-2021 Carlos Amengual
  */
+
+/**
+ * Scalable Vector Graphics (SVG) Java binding.
+ * <p>
+ * This is a Java binding for an old version of the SVG DOM API (SVGOM). It is
+ * compatible with the SVGOM API used by Apache Batik (which uses the SVGOM
+ * packages at the <a href=
+ * "http://archive.apache.org/dist/xml/commons/xml-commons-external-1.3.04-src.zip">{@code xml-apis-ext-1.3.04}</a>
+ * package), that seem to be a mixture of the
+ * <a href="http://www.w3.org/TR/2000/CR-SVG-20000802/java-binding.zip">SVG
+ * 1.0</a> and
+ * <a href="http://www.w3.org/TR/2011/REC-SVG11-20110816/java-binding.zip">SVG
+ * 1.1</a> bindings.
+ * </p>
+ * <p>
+ * Some method signatures were modified so they match the implementations in
+ * Apache Batik/EchoSVG.
+ * </p>
+ */
 module org.w3c.dom.svg {
 	exports org.w3c.dom.svg;
 

svgom-api/src/main/java/org/w3c/dom/svg/SVGElement.java

@@ -16,15 +16,39 @@
 import org.w3c.dom.Element;
 
 public interface SVGElement extends Element {
+
+	/**
+	 * Gets the {@code id} content attribute.
+	 * 
+	 * @return the value of the {@code id} attribute, or the empty string if none.
+	 */
 	public String getId();
 
+	/**
+	 * Sets the {@code id} content attribute.
+	 * 
+	 * @param id the value of the {@code id} attribute.
+	 * @throws DOMException
+	 */
 	public void setId(String id) throws DOMException;
 
 	public String getXMLbase();
 
 	public void setXMLbase(String xmlbase) throws DOMException;
 
+	/**
+	 * Gets the nearest ancestor {@code svg} element.
+	 * 
+	 * @return the nearest ancestor {@code svg} element, or {@code null} if the
+	 *         current element is the outermost {@code svg} element.
+	 */
 	public SVGSVGElement getOwnerSVGElement();
 
+	/**
+	 * Get the element that provides the SVG viewport for this element.
+	 * 
+	 * @return the nearest ancestor element that establishes an SVG viewport, or
+	 *         {@code null} if the current element is the outermost svg element.
+	 */
 	public SVGElement getViewportElement();
 }