SCBC-493: Fix issues with Scala 3 scaladoc generation

The Scala 3 build cannot currently be uploaded to
Maven Central due to as the javadocs jar is not available.

Producing this jar turns out to be very challenging,
as the scala-maven-plugin does not support it in Scala 3:

davidB/scala-maven-plugin#862

For now, we will produce an empty javadocs jar for this
build.

Change-Id: I5b9986c32cd4cd166d601326478fc4509f5347f6
Reviewed-on: https://review.couchbase.org/c/couchbase-jvm-clients/+/232259
Tested-by: Build Bot <[email protected]>
Reviewed-by: David Nault <[email protected]>

Author: programmatix

pom.xml

@@ -58,7 +58,7 @@
         <maven-javadoc-plugin.version>3.11.2</maven-javadoc-plugin.version>
         <build-helper-maven-plugin.version>3.2.0</build-helper-maven-plugin.version>
         <flatten-maven-plugin.version>1.7.0</flatten-maven-plugin.version>
-        <scala-maven-plugin.version>4.8.1</scala-maven-plugin.version>
+        <scala-maven-plugin.version>4.9.5</scala-maven-plugin.version>
         <mvn-scalafmt.version>1.1.1713302731.c3d0074</mvn-scalafmt.version>
 
         <!-- When changing this, make sure to update these versions:

scala-client/pom.xml

@@ -532,6 +532,35 @@
                             </execution>
                         </executions>
                     </plugin>
+
+                    <!-- scala-maven-plugin does not support scaladocs together with Scala 3:
+                         https://github.com/davidB/scala-maven-plugin/issues/862
+                         so we attach an empty javadocs to satisfy Maven Central.
+
+                         The Scala 2 builds continue to provide scaladocs as usual.
+                         -->
+                    <plugin>
+                        <groupId>org.apache.maven.plugins</groupId>
+                        <artifactId>maven-javadoc-plugin</artifactId>
+                        <version>${maven-javadoc-plugin.version}</version>
+                        <executions>
+                            <execution>
+                                <id>attach-javadocs</id>
+                                <goals>
+                                    <goal>jar</goal>
+                                </goals>
+                                <configuration>
+                                    <sourcepath>${project.basedir}/src/main/java</sourcepath>
+                                    <sourceFileIncludes>com/couchbase/client/scala/internal/**/*.java</sourceFileIncludes>
+                                    <show>private</show>
+                                    <source>8</source>
+                                    <doclint>none</doclint>
+                                    <quiet>true</quiet>
+                                    <stylesheetfile>${project.basedir}/../config/javadoc/style.css</stylesheetfile>
+                                </configuration>
+                            </execution>
+                        </executions>
+                    </plugin>
                 </plugins>
             </build>
         </profile>

scala-client/src/main/java/com/couchbase/client/scala/internal/JavadocPlaceholder.java

@@ -0,0 +1,25 @@
+/*
+ * Copyright 2025 Couchbase, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.couchbase.client.scala.internal;
+
+/**
+ * Empty API docs are generated for the Scala 3 build at this time, due to known incompatibilies between Maven and Scala 3:
+ * https://github.com/davidB/scala-maven-plugin/issues/862
+ */
+@Deprecated
+class JavadocPlaceholder {
+}

scala-implicits/src/main/java/com/couchbase/client/scala/internal/JavadocPlaceholder.java

@@ -0,0 +1,25 @@
+/*
+ * Copyright 2025 Couchbase, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.couchbase.client.scala.internal;
+
+/**
+ * Empty API docs are generated for the Scala 3 build at this time, due to known incompatibilies between Maven and Scala 3:
+ * https://github.com/davidB/scala-maven-plugin/issues/862
+ */
+@Deprecated
+class JavadocPlaceholder {
+}