Merge branch 'main' of github.com:hal/elemento

.github/workflows/apidocs.yml

@@ -22,7 +22,7 @@ jobs:
           $MVN -P snippets javadoc:aggregate
           $MVN -P snippets javadoc:javadoc
           $MVN -P snippets org.apache.maven.plugins:maven-antrun-plugin:run@copy-apidocs
-      - uses: JamesIves/[email protected].1
+      - uses: JamesIves/[email protected].2
         with:
           branch: gh-pages
           folder: ./target/reports/apidocs

.github/workflows/release.yml

@@ -52,7 +52,7 @@ jobs:
           $MVN -P snippets javadoc:aggregate
           $MVN -P snippets javadoc:javadoc
           $MVN -P snippets org.apache.maven.plugins:maven-antrun-plugin:run@copy-apidocs
-      - uses: JamesIves/[email protected].1
+      - uses: JamesIves/[email protected].2
         with:
           branch: gh-pages
           folder: ./target/reports/apidocs
@@ -72,7 +72,7 @@ jobs:
           distribution: temurin
           cache: maven
       - run: $MVN --projects org.jboss.elemento:elemento-samples-dist --also-make -P samples install
-      - uses: JamesIves/[email protected].1
+      - uses: JamesIves/[email protected].2
         with:
           branch: gh-pages
           folder: ./samples/dist/target/samples

docs/builder-api.md

@@ -20,8 +20,7 @@ Creating a hierarchy of elements is often awkward and cumbersome when working wi
 </section>
 ```
 
-lead to a vast amount of `Document.createElement()` and chained `Node.appendChild()` calls. With Elemento, creating the above
-structure is as easy as
+lead to a vast amount of `Document.createElement()` and chained `Node.appendChild()` calls. With Elemento, creating the above structure is as easy as
 
 ```java
 import static org.jboss.elemento.Elements.*;
@@ -45,14 +44,11 @@ HTMLElement section = section().css("main")
         .element();
 ```
 
-The class `Elements` provides convenient methods to create the most common elements. It uses a fluent API to create and append
-elements on the fly. Take a look at
-the [API documentation](https://hal.github.io/elemento/apidocs/org/jboss/elemento/Elements.html) for more details.
+The class `Elements` provides convenient methods to create the most common elements. It uses a fluent API to create and append elements on the fly. Take a look at the [API documentation](https://hal.github.io/elemento/apidocs/org/jboss/elemento/Elements.html) for more details.
 
 ## References
 
-When creating large hierarchies of elements, you often need to assign an element somewhere in the tree. Use an inline assignment
-together with `element()` to create and assign the element in one go:
+When creating large hierarchies of elements, you often need to assign an element somewhere in the tree. Use an inline assignment together with `element()` to create and assign the element in one go:
 
 ```java
 import static org.jboss.elemento.Elements.*;
@@ -67,56 +63,30 @@ final HTMLElement footer = footer()
 
 The builders in Elemento are of one of the following classes:
 
-- [`HTMLContainerBuilder<E extends HTMLElement>`](https://hal.github.io/elemento/apidocs/org/jboss/elemento/HTMLContainerBuilder.html)
-- [`HTMLElementBuilder<E extends HTMLElement>`](https://hal.github.io/elemento/apidocs/org/jboss/elemento/HTMLElementBuilder.html)
-- [`HTMLInputElementBuilder<E extends HTMLInputElement>`](https://hal.github.io/elemento/apidocs/org/jboss/elemento/HTMLInputElementBuilder.html)
-- [`HTMLTextAreaElementBuilder<E extends HTMLTextAreaElement>`](https://hal.github.io/elemento/apidocs/org/jboss/elemento/HTMLTextAreaElementBuilder.html)
+* [`HTMLContainerBuilder<E extends HTMLElement>`](https://hal.github.io/elemento/apidocs/org/jboss/elemento/HTMLContainerBuilder.html)
+* [`HTMLElementBuilder<E extends HTMLElement>`](https://hal.github.io/elemento/apidocs/org/jboss/elemento/HTMLElementBuilder.html)
+* [`HTMLInputElementBuilder<E extends HTMLInputElement>`](https://hal.github.io/elemento/apidocs/org/jboss/elemento/HTMLInputElementBuilder.html)
+* [`HTMLTextAreaElementBuilder<E extends HTMLTextAreaElement>`](https://hal.github.io/elemento/apidocs/org/jboss/elemento/HTMLTextAreaElementBuilder.html)
 
 For [MathML](mathml.md) and [SVG](svg.md), the builders are
 
-- [`MathMLElementBuilder<E extends MathMLElement>`](https://hal.github.io/elemento/apidocs/org/jboss/elemento/mathml/MathMLElementBuilder.html)
-- [`SVGElementBuilder<E extends SVGElement>`](https://hal.github.io/elemento/apidocs/org/jboss/elemento/svg/SVGElementBuilder.html)
-- [`SVGContainerBuilder<E extends SVGElement>`](https://hal.github.io/elemento/apidocs/org/jboss/elemento/svg/SVGContainerBuilder.html)
+* [`MathMLElementBuilder<E extends MathMLElement>`](https://hal.github.io/elemento/apidocs/org/jboss/elemento/mathml/MathMLElementBuilder.html)
+* [`SVGElementBuilder<E extends SVGElement>`](https://hal.github.io/elemento/apidocs/org/jboss/elemento/svg/SVGElementBuilder.html)
+* [`SVGContainerBuilder<E extends SVGElement>`](https://hal.github.io/elemento/apidocs/org/jboss/elemento/svg/SVGContainerBuilder.html)
 
-All builders encapsulate a given element and implement `TypedBuilder<T, B extends TypedBuilder<T, B>>` to make builders work
-with inheritance. Apart from that, all builders are kept very simple and don't define their own methods. For example, this is
-the definition of the `HTMLElementBuilder`:
+All builders encapsulate a given element and implement `TypedBuilder<T, B extends TypedBuilder<T, B>>` to make builders work with inheritance. Apart from that, all builders are kept very simple and don't define their own methods. For example, this is the definition of the [`HTMLContainerBuilder`](https://hal.github.io/elemento/apidocs/org/jboss/elemento/HTMLContainerBuilder.html):
 
-```java
-public class HTMLElementBuilder<E extends HTMLElement> { // implements section omitted
-
-    private final E element;
-
-    public HTMLElementBuilder(E element) {
-        this.element = requireNonNull(element, "element required");
-    }
-
-    @Override
-    public HTMLElementBuilder<E> that() {
-        return this;
-    }
-
-    @Override
-    public E element() {
-        return element;
-    }
-}
-```
+{% @github-files/github-code-block url="https://github.com/hal/elemento/blob/main/core/src/main/java/org/jboss/elemento/HTMLContainerBuilder.java" %}
 
-The builders get their features solely by implementing specific interfaces. These interfaces contain default methods to
-manipulate the encapsulated element in a specific way.
+The builders get their features solely by implementing specific interfaces. These interfaces contain default methods to manipulate the encapsulated element in a specific way.
 
 The interface names follow the pattern `[HTML|MathML|SVG]Element<Scope>Methods`. Some examples are
 
-- [`ElementAttributeMethods`](https://hal.github.io/elemento/apidocs/org/jboss/elemento/ElementAttributeMethods.html)
-- [`HTMLElementDataMethods`](https://hal.github.io/elemento/apidocs/org/jboss/elemento/HTMLElementDataMethods.html)
-- [`HTMLInputElementMethods`](https://hal.github.io/elemento/apidocs/org/jboss/elemento/HTMLInputElementMethods.html)
-- [`SVGElementStyleMethods`](https://hal.github.io/elemento/apidocs/org/jboss/elemento/SVGElementStyleMethods.html)
+* [`ElementAttributeMethods`](https://hal.github.io/elemento/apidocs/org/jboss/elemento/ElementAttributeMethods.html)
+* [`HTMLElementDataMethods`](https://hal.github.io/elemento/apidocs/org/jboss/elemento/HTMLElementDataMethods.html)
+* [`HTMLInputElementMethods`](https://hal.github.io/elemento/apidocs/org/jboss/elemento/HTMLInputElementMethods.html)
+* [`SVGElementStyleMethods`](https://hal.github.io/elemento/apidocs/org/jboss/elemento/SVGElementStyleMethods.html)
 
-If you only use Elemento to create a DOM tree quickly and easily, you won't most likely come into touch with these _method_
-interfaces. However, if you want to create your own builders, the interfaces come in very handy. You can have very
-fine-grained control over which methods your builder should provide. And since these methods are defined as default methods in
-interfaces, you are free to mix and match the interfaces across different builders without worrying about multiple inheritance.
+If you only use Elemento to create a DOM tree quickly and easily, you won't most likely come into touch with these _method_ interfaces. However, if you want to create your own builders, the interfaces come in very handy. You can have very fine-grained control over which methods your builder should provide. And since these methods are defined as default methods in interfaces, you are free to mix and match the interfaces across different builders without worrying about multiple inheritance.
 
-The components in [PatternFly Java](https://patternfly-java.github.io/api-design) are a good example of this. They build upon
-Elemento's builders and implement specific _method_ interfaces to define their features.
+The components in [PatternFly Java](https://patternfly-java.github.io/api-design) are a good example of this. They build upon Elemento's builders and implement specific _method_ interfaces to define their features.