8240137: Support chained use of Content.add

Reviewed-by: hannesw

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDocletWriter.java

@@ -1357,8 +1357,8 @@ public Content commentTagsToContent(DocTree holderTag,
     {
         final Content result = new ContentBuilder() {
             @Override
-            public void add(CharSequence text) {
-                super.add(utils.normalizeNewlines(text));
+            public ContentBuilder add(CharSequence text) {
+                return super.add(utils.normalizeNewlines(text));
             }
         };
         CommentHelper ch = utils.getCommentHelper(element);

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/markup/Comment.java

@@ -52,28 +52,6 @@ public Comment(String comment) {
         commentText = nullCheck(comment);
     }
 
-    /**
-     * This method is not supported by the class.
-     *
-     * @param content content that needs to be added
-     * @throws UnsupportedOperationException always
-     */
-    @Override
-    public void add(Content content) {
-        throw new UnsupportedOperationException();
-    }
-
-    /**
-     * This method is not supported by the class.
-     *
-     * @param stringContent string content that needs to be added
-     * @throws UnsupportedOperationException always
-     */
-    @Override
-    public void add(CharSequence stringContent) {
-        throw new UnsupportedOperationException();
-    }
-
     @Override
     public boolean isEmpty() {
         return commentText.isEmpty();

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/markup/ContentBuilder.java

@@ -48,28 +48,30 @@ public ContentBuilder(Content... contents) {
     }
 
     @Override
-    public void add(Content content) {
+    public ContentBuilder add(Content content) {
         nullCheck(content);
         ensureMutableContents();
         if (content instanceof ContentBuilder) {
             contents.addAll(((ContentBuilder) content).contents);
         } else
             contents.add(content);
+        return this;
     }
 
     @Override
-    public void add(CharSequence text) {
-        if (text.length() == 0)
-            return;
-        ensureMutableContents();
-        Content c = contents.isEmpty() ? null : contents.get(contents.size() - 1);
-        StringContent sc;
-        if (c != null && c instanceof StringContent) {
-            sc = (StringContent) c;
-        } else {
-            contents.add(sc = new StringContent());
+    public ContentBuilder add(CharSequence text) {
+        if (text.length() > 0) {
+            ensureMutableContents();
+            Content c = contents.isEmpty() ? null : contents.get(contents.size() - 1);
+            StringContent sc;
+            if (c != null && c instanceof StringContent) {
+                sc = (StringContent) c;
+            } else {
+                contents.add(sc = new StringContent());
+            }
+            sc.add(text);
         }
-        sc.add(text);
+        return this;
     }
 
     @Override

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/markup/Entity.java

@@ -51,16 +51,6 @@ private Entity(String text) {
         this.text = text;
     }
 
-    @Override
-    public void add(Content content) {
-        throw new UnsupportedOperationException();
-    }
-
-    @Override
-    public void add(CharSequence stringContent) {
-        throw new UnsupportedOperationException();
-    }
-
     @Override
     public boolean write(Writer writer, boolean atNewline) throws IOException {
         writer.write(text);

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/markup/FixedStringContent.java

@@ -50,29 +50,6 @@ public FixedStringContent(CharSequence content) {
         string = Entity.escapeHtmlChars(content);
     }
 
-    /**
-     * This method is not supported by the class.
-     *
-     * @param content content that needs to be added
-     * @throws UnsupportedOperationException always
-     */
-    @Override
-    public void add(Content content) {
-        throw new UnsupportedOperationException();
-    }
-
-    /**
-     * Adds content for the StringContent object.  The method escapes
-     * HTML characters for the string content that is added.
-     *
-     * @param strContent string content to be added
-     * @throws UnsupportedOperationException always
-     */
-    @Override
-    public void add(CharSequence strContent) {
-        throw new UnsupportedOperationException();
-    }
-
     @Override
     public boolean isEmpty() {
         return string.isEmpty();

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/markup/HtmlTree.java

@@ -150,20 +150,19 @@ public HtmlTree setStyle(HtmlStyle style) {
     /**
      * Adds content for the HTML tag.
      *
-     * @param tagContent tag content to be added
+     * @param content content to be added
      */
     @Override
-    public void add(Content tagContent) {
-        if (tagContent instanceof ContentBuilder) {
-            for (Content c: ((ContentBuilder)tagContent).contents) {
-                add(c);
-            }
+    public HtmlTree add(Content content) {
+        if (content instanceof ContentBuilder) {
+            ((ContentBuilder) content).contents.forEach(this::add);
         }
-        else if (tagContent == HtmlTree.EMPTY || tagContent.isValid()) {
-            if (content.isEmpty())
-                content = new ArrayList<>();
-            content.add(tagContent);
+        else if (content == HtmlTree.EMPTY || content.isValid()) {
+            if (this.content.isEmpty())
+                this.content = new ArrayList<>();
+            this.content.add(content);
         }
+        return this;
     }
 
     /**
@@ -174,16 +173,19 @@ else if (tagContent == HtmlTree.EMPTY || tagContent.isValid()) {
      * @param stringContent string content that needs to be added
      */
     @Override
-    public void add(CharSequence stringContent) {
+    public HtmlTree add(CharSequence stringContent) {
         if (!content.isEmpty()) {
             Content lastContent = content.get(content.size() - 1);
             if (lastContent instanceof StringContent)
                 lastContent.add(stringContent);
-            else
+            else {
                 add(new StringContent(stringContent));
+            }
         }
-        else
+        else {
             add(new StringContent(stringContent));
+        }
+        return this;
     }
 
     @Override

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/markup/RawHtml.java

@@ -52,28 +52,6 @@ public RawHtml(CharSequence rawHtml) {
         rawHtmlContent = rawHtml.toString();
     }
 
-    /**
-     * This method is not supported by the class.
-     *
-     * @param content content that needs to be added
-     * @throws UnsupportedOperationException always
-     */
-    @Override
-    public void add(Content content) {
-        throw new UnsupportedOperationException();
-    }
-
-    /**
-     * This method is not supported by the class.
-     *
-     * @param stringContent string content that needs to be added
-     * @throws UnsupportedOperationException always
-     */
-    @Override
-    public void add(CharSequence stringContent) {
-        throw new UnsupportedOperationException();
-    }
-
     @Override
     public boolean isEmpty() {
         return rawHtmlContent.isEmpty();

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/markup/Script.java

@@ -108,15 +108,11 @@ public Content asContent() {
         ScriptContent scriptContent = new ScriptContent(sb);
         HtmlTree tree = new HtmlTree(HtmlTag.SCRIPT) {
             @Override
-            public void add(CharSequence s) {
-                throw new UnsupportedOperationException();
-            }
-            @Override
-            public void add(Content c) {
+            public HtmlTree add(Content c) {
                 if (c != scriptContent) {
                     throw new IllegalArgumentException();
                 }
-                super.add(scriptContent);
+                return super.add(scriptContent);
             }
         };
         tree.put(HtmlAttr.TYPE, "text/javascript");
@@ -200,13 +196,9 @@ private static class ScriptContent extends Content {
         }
 
         @Override
-        public void add(Content content) {
-            throw new UnsupportedOperationException();
-        }
-
-        @Override
-        public void add(CharSequence code) {
+        public ScriptContent add(CharSequence code) {
             sb.append(code);
+            return this;
         }
 
         @Override

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/markup/StringContent.java

@@ -60,26 +60,16 @@ public StringContent(CharSequence initialContent) {
         Entity.escapeHtmlChars(initialContent, stringContent);
     }
 
-    /**
-     * This method is not supported by the class.
-     *
-     * @param content content that needs to be added
-     * @throws UnsupportedOperationException always
-     */
-    @Override
-    public void add(Content content) {
-        throw new UnsupportedOperationException();
-    }
-
     /**
      * Adds content for the StringContent object.  The method escapes
      * HTML characters for the string content that is added.
      *
      * @param strContent string content to be added
      */
     @Override
-    public void add(CharSequence strContent) {
+    public StringContent add(CharSequence strContent) {
         Entity.escapeHtmlChars(strContent, stringContent);
+        return this;
     }
 
     @Override

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/markup/Table.java

@@ -288,7 +288,7 @@ public Table setId(String id) {
     }
 
     /**
-     * Add a row of data to the table.
+     * Adds a row of data to the table.
      * Each item of content should be suitable for use as the content of a
      * {@code <th>} or {@code <td>} cell.
      * This method should not be used when the table has tabs: use a method
@@ -301,7 +301,7 @@ public void addRow(Content... contents) {
     }
 
     /**
-     * Add a row of data to the table.
+     * Adds a row of data to the table.
      * Each item of content should be suitable for use as the content of a
      * {@code <th>} or {@code <td> cell}.
      * This method should not be used when the table has tabs: use a method
@@ -314,14 +314,14 @@ public void addRow(List<Content> contents) {
     }
 
     /**
-     * Add a row of data to the table.
+     * Adds a row of data to the table.
      * Each item of content should be suitable for use as the content of a
      * {@code <th>} or {@code <td>} cell.
      *
      * If tabs have been added to the table, the specified element will be used
      * to determine whether the row should be displayed when any particular tab
      * is selected, using the predicate specified when the tab was
-     * {@link #add(String,Predicate) added}.
+     * {@link #addTab(String,Predicate) added}.
      *
      * @param element the element
      * @param contents the contents for the row
@@ -333,14 +333,14 @@ public void addRow(Element element, Content... contents) {
     }
 
     /**
-     * Add a row of data to the table.
+     * Adds a row of data to the table.
      * Each item of content should be suitable for use as the content of a
      * {@code <th>} or {@code <td>} cell.
      *
      * If tabs have been added to the table, the specified element will be used
      * to determine whether the row should be displayed when any particular tab
      * is selected, using the predicate specified when the tab was
-     * {@link #add(String,Predicate) added}.
+     * {@link #addTab(String,Predicate) added}.
      *
      * @param element the element
      * @param contents the contents for the row

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/Content.java

@@ -59,17 +59,36 @@ public String toString() {
 
     /**
      * Adds content to the existing content.
+     * This is an optional operation.
      *
-     * @param content content that needs to be added
+     * @implSpec This implementation throws {@linkplain UnsupportedOperationException}.
+     *
+     * @param content content to be added
+     * @return this object
+     * @throws UnsupportedOperationException if this operation is not supported by
+     *                                       a particular implementation
+     * @throws IllegalArgumentException      if the content is not suitable to be added
      */
-    public abstract void add(Content content);
+    public Content add(Content content) {
+        throw new UnsupportedOperationException();
+    }
 
     /**
      * Adds a string content to the existing content.
+     * This is an optional operation.
+     *
+     * @implSpec
+     * This implementation throws {@linkplain UnsupportedOperationException}.
      *
      * @param stringContent the string content to be added
+     * @return this object
+     * @throws UnsupportedOperationException if this operation is not supported by
+     *                                       a particular implementation
+     * @throws IllegalArgumentException      if the content is not suitable to be added
      */
-    public abstract void add(CharSequence stringContent);
+    public Content add(CharSequence stringContent) {
+        throw new UnsupportedOperationException();
+    }
 
     /**
      * Writes content to a writer.