8297984: Turn on warnings as errors for javadoc

Reviewed-by: serb, erikj

Author: magicus

.github/workflows/main.yml

@@ -35,7 +35,7 @@ on:
       platforms:
         description: 'Platform(s) to execute on (comma separated, e.g. "linux-x64, macos, aarch64")'
         required: true
-        default: 'linux-x64, linux-x86, linux-x64-variants, linux-cross-compile, macos-x64, macos-aarch64, windows-x64, windows-aarch64'
+        default: 'linux-x64, linux-x86, linux-x64-variants, linux-cross-compile, macos-x64, macos-aarch64, windows-x64, windows-aarch64, docs'
       configure-arguments:
         description: 'Additional configure arguments'
         required: false
@@ -65,6 +65,7 @@ jobs:
       macos-aarch64: ${{ steps.include.outputs.macos-aarch64 }}
       windows-x64: ${{ steps.include.outputs.windows-x64 }}
       windows-aarch64: ${{ steps.include.outputs.windows-aarch64 }}
+      docs: ${{ steps.include.outputs.docs }}
 
     steps:
         # This function must be inlined in main.yml, or we'd be forced to checkout the repo
@@ -116,6 +117,7 @@ jobs:
           echo "macos-aarch64=$(check_platform macos-aarch64 macos aarch64)" >> $GITHUB_OUTPUT
           echo "windows-x64=$(check_platform windows-x64 windows x64)" >> $GITHUB_OUTPUT
           echo "windows-aarch64=$(check_platform windows-aarch64 windows aarch64)" >> $GITHUB_OUTPUT
+          echo "docs=$(check_platform docs)" >> $GITHUB_OUTPUT
 
   ###
   ### Build jobs
@@ -276,6 +278,23 @@ jobs:
       make-arguments: ${{ github.event.inputs.make-arguments }}
     if: needs.select.outputs.windows-aarch64 == 'true'
 
+  build-docs:
+    name: docs
+    needs: select
+    uses: ./.github/workflows/build-linux.yml
+    with:
+      platform: linux-x64
+      debug-levels: '[ "debug" ]'
+      make-target: 'docs-jdk-bundles'
+      # Make sure we never try to make full docs, since that would require a
+      # build JDK, and we do not need the additional testing of the graphs.
+      extra-conf-options: '--disable-full-docs'
+      gcc-major-version: '10'
+      apt-gcc-version: '10.4.0-4ubuntu1~22.04'
+      configure-arguments: ${{ github.event.inputs.configure-arguments }}
+      make-arguments: ${{ github.event.inputs.make-arguments }}
+    if: needs.select.outputs.docs == 'true'
+
   ###
   ### Test jobs
   ###

make/Docs.gmk

@@ -102,6 +102,10 @@ REFERENCE_TAGS := $(JAVADOC_TAGS)
 JAVADOC_DISABLED_DOCLINT_WARNINGS := missing
 JAVADOC_DISABLED_DOCLINT_PACKAGES := org.w3c.* javax.smartcardio
 
+# Allow overriding on the command line
+# (intentionally sharing name with the javac option)
+JAVA_WARNINGS_ARE_ERRORS ?= -Werror
+
 # The initial set of options for javadoc
 JAVADOC_OPTIONS := -use -keywords -notimestamp \
     -encoding ISO-8859-1 -docencoding UTF-8 -breakiterator \
@@ -333,6 +337,7 @@ define SetupApiDocsGenerationBody
   # Ignore the doclint warnings in certain packages
   $1_OPTIONS += -Xdoclint/package:$$(call CommaList, $$(addprefix -, \
       $$(JAVADOC_DISABLED_DOCLINT_PACKAGES)))
+  $1_OPTIONS += $$(JAVA_WARNINGS_ARE_ERRORS)
 
   $1_DOC_TITLE := $$($1_LONG_NAME)<br>Version $$(VERSION_SPECIFICATION) API \
       Specification

src/jdk.jfr/share/classes/jdk/jfr/consumer/RecordingStream.java

@@ -394,7 +394,7 @@ public void startAsync() {
      * The following code snippet illustrates how this method can be used in
      * conjunction with the {@link #startAsync()} method to monitor what happens
      * during a test method:
-     * <p>
+     *
      * {@snippet class="Snippets" region="RecordingStreamStop"}
      *
      * @return {@code true} if recording is stopped, {@code false} otherwise