TEZ-4694 Add package-level Javadoc descriptions so generated API docs show a short summary for each package

pom.xml

@@ -87,6 +87,7 @@
     <lifecycle-mapping.version>1.0.0</lifecycle-mapping.version>
     <maven-checkstyle-plugin.version>3.6.0</maven-checkstyle-plugin.version>
     <maven-enforcer-plugin.version>3.0.0</maven-enforcer-plugin.version>
+    <maven-javadoc-plugin.version>3.12.0</maven-javadoc-plugin.version>
     <maven-project-info-reports-plugin.version>3.1.2</maven-project-info-reports-plugin.version>
     <maven-shade-plugin.version>3.6.0</maven-shade-plugin.version>
     <maven-site-plugin.version>3.12.1</maven-site-plugin.version>
@@ -897,6 +898,7 @@
         <plugin>
           <groupId>org.apache.maven.plugins</groupId>
           <artifactId>maven-javadoc-plugin</artifactId>
+          <version>${maven-javadoc-plugin.version}</version>
           <configuration>
             <doclint>none</doclint>
           </configuration>

tez-api/src/main/java/org/apache/tez/client/package-info.java

@@ -0,0 +1,27 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you 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.
+ */
+
+/**
+ * Client API for creating Tez sessions, building and submitting DAGs, and monitoring applications.
+ */
+@Public
+@Evolving
+package org.apache.tez.client;
+
+import org.apache.hadoop.classification.InterfaceAudience.Public;
+import org.apache.hadoop.classification.InterfaceStability.Evolving;

tez-api/src/main/java/org/apache/tez/client/registry/package-info.java

@@ -16,6 +16,10 @@
  * limitations under the License.
  */
 
+/**
+ * Registry and discovery for the Tez Application Master (AM).
+ * Enables clients to locate the AM and optional ZooKeeper-based implementation.
+ */
 @Public
 @Evolving
 package org.apache.tez.client.registry;

tez-api/src/main/java/org/apache/tez/client/registry/zookeeper/package-info.java

@@ -16,6 +16,10 @@
  * limitations under the License.
  */
 
+/**
+ * ZooKeeper-based AM registry implementation.
+ * Enables clients to discover the Tez AM via ZooKeeper.
+ */
 @Public
 @Evolving
 package org.apache.tez.client.registry.zookeeper;

tez-api/src/main/java/org/apache/tez/common/annotation/package-info.java

@@ -0,0 +1,27 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you 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.
+ */
+
+/**
+ * Annotations for configuration properties and related metadata used by the Tez API.
+ */
+@Public
+@Evolving
+package org.apache.tez.common.annotation;
+
+import org.apache.hadoop.classification.InterfaceAudience.Public;
+import org.apache.hadoop.classification.InterfaceStability.Evolving;

tez-api/src/main/java/org/apache/tez/common/counters/TaskCounter.java

@@ -140,13 +140,13 @@ public enum TaskCounter {
   ADDITIONAL_SPILLS_BYTES_WRITTEN,
 
   /**
-   * Bytes read from disk due to previous spills (lac of adequate memory).
+   * Bytes read from disk due to previous spills (lack of adequate memory).
    * Used by OnFileSortedOutput and ShuffledMergedInput
    */
   ADDITIONAL_SPILLS_BYTES_READ,
 
   /**
-   * Spills that were generated & read by the same task (unnecessary spills due to lac of
+   * Spills that were generated & read by the same task (unnecessary spills due to lack of
    * adequate memory).
    *
    * Used by OnFileSortedOutput
@@ -202,7 +202,7 @@ public enum TaskCounter {
 
   /**
    * Time taken to shuffle data. This includes time taken to fetch the data
-   * & merging the data in parallel to fetching when needed.  This also includes any
+   * & merging the data in parallel to fetching when needed.  This also includes any
    * waiting time related to event delays from source.
    *
    * Represented in milliseconds.

tez-api/src/main/java/org/apache/tez/common/counters/package-info.java

@@ -0,0 +1,27 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you 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.
+ */
+
+/**
+ * Counter types and groups for DAG, task, and framework metrics.
+ */
+@Public
+@Evolving
+package org.apache.tez.common.counters;
+
+import org.apache.hadoop.classification.InterfaceAudience.Public;
+import org.apache.hadoop.classification.InterfaceStability.Evolving;

tez-api/src/main/java/org/apache/tez/common/package-info.java

@@ -0,0 +1,27 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you 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.
+ */
+
+/**
+ * Common utilities, helpers, and shared types used across the Tez API module.
+ */
+@Public
+@Evolving
+package org.apache.tez.common;
+
+import org.apache.hadoop.classification.InterfaceAudience.Public;
+import org.apache.hadoop.classification.InterfaceStability.Evolving;

tez-api/src/main/java/org/apache/tez/common/security/package-info.java

@@ -0,0 +1,27 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you 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.
+ */
+
+/**
+ * Security utilities: job tokens, ACLs, and access control for Tez applications.
+ */
+@Public
+@Evolving
+package org.apache.tez.common.security;
+
+import org.apache.hadoop.classification.InterfaceAudience.Public;
+import org.apache.hadoop.classification.InterfaceStability.Evolving;

tez-api/src/main/java/org/apache/tez/dag/api/TezConfiguration.java

@@ -784,7 +784,7 @@ public TezConfiguration(boolean loadDefaults) {
 
   /**
    * Int value. The maximum number of attempts that can run concurrently for a given vertex.
-   * Setting <=0 implies no limit
+   * Setting &lt;=0 implies no limit
    */
   @ConfigurationScope(Scope.VERTEX)
   @ConfigurationProperty(type="integer")
@@ -1106,7 +1106,7 @@ public TezConfiguration(boolean loadDefaults) {
    * for this interval then the task will be considered hung and terminated.
    * The value for this config should be larger than {@link TezConfiguration#TASK_HEARTBEAT_TIMEOUT_MS}
    * and larger than 2 times the value of {@link TezConfiguration#TEZ_TASK_AM_HEARTBEAT_INTERVAL_MS}.
-   * A config value <=0 disables this.
+   * A config value &lt;=0 disables this.
    */
   @ConfigurationScope(Scope.VERTEX)
   @ConfigurationProperty
@@ -1337,7 +1337,7 @@ public TezConfiguration(boolean loadDefaults) {
    * must be +ve and >=
    * TezConfiguration#TEZ_AM_CONTAINER_IDLE_RELEASE_TIMEOUT_MIN_MILLIS.
    * Containers will have an expire time set to a random value between
-   * TezConfiguration#TEZ_AM_CONTAINER_IDLE_RELEASE_TIMEOUT_MIN_MILLIS &&
+   * TezConfiguration#TEZ_AM_CONTAINER_IDLE_RELEASE_TIMEOUT_MIN_MILLIS &amp;&amp;
    * TezConfiguration#TEZ_AM_CONTAINER_IDLE_RELEASE_TIMEOUT_MAX_MILLIS. This
    * creates a graceful reduction in the amount of idle resources held
    */

tez-api/src/main/java/org/apache/tez/dag/api/Vertex.java

@@ -160,7 +160,7 @@ public static Vertex create(String vertexName, ProcessorDescriptor processorDesc
   /**
    * Create a new vertex with the given name and parallelism. <br>
    * The vertex task resource will be picked from configuration
-   * {@link TezConfiguration#TEZ_TASK_RESOURCE_MEMORY_MB} &
+   * {@link TezConfiguration#TEZ_TASK_RESOURCE_MEMORY_MB} &amp;
    * {@link TezConfiguration#TEZ_TASK_RESOURCE_CPU_VCORES} Applications that
    * want more control over their task resource specification may create their
    * own logic to determine task resources and use

tez-api/src/main/java/org/apache/tez/dag/api/VertexGroup.java

@@ -34,7 +34,7 @@
  * the destination vertex see a single input named after the VertexGroup instead
  * multiple inputs from the members of the VertexGroup.
  * An output can be added to a VertexGroup.
- * All outgoing edges & outputs of a VertexGroup are automatically transferred to the
+ * All outgoing edges & outputs of a VertexGroup are automatically transferred to the
  * member vertices of the VertexGroup.
  * A VertexGroup is not part of the final DAG.
  */

tez-api/src/main/java/org/apache/tez/dag/api/client/package-info.java

@@ -0,0 +1,27 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you 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.
+ */
+
+/**
+ * Client API for monitoring and controlling a running DAG (status, timeline, vertex updates).
+ */
+@Public
+@Evolving
+package org.apache.tez.dag.api.client;
+
+import org.apache.hadoop.classification.InterfaceAudience.Public;
+import org.apache.hadoop.classification.InterfaceStability.Evolving;

tez-api/src/main/java/org/apache/tez/dag/api/client/rpc/package-info.java

@@ -16,6 +16,10 @@
  * limitations under the License.
  */
 
+/**
+ * Internal RPC protocol definitions for DAG client to AM communication.
+ * Used by the generated Protobuf-based DAG client stub.
+ */
 @Private
 package org.apache.tez.dag.api.client.rpc;
 

tez-api/src/main/java/org/apache/tez/dag/api/event/package-info.java

@@ -0,0 +1,27 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you 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.
+ */
+
+/**
+ * Event types for DAG and vertex state updates delivered to the client.
+ */
+@Public
+@Evolving
+package org.apache.tez.dag.api.event;
+
+import org.apache.hadoop.classification.InterfaceAudience.Public;
+import org.apache.hadoop.classification.InterfaceStability.Evolving;

tez-api/src/main/java/org/apache/tez/dag/api/package-info.java

@@ -0,0 +1,27 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you 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.
+ */
+
+/**
+ * Core DAG API: DAG, Vertex, Edge, and descriptor types for defining Tez dataflow graphs.
+ */
+@Public
+@Evolving
+package org.apache.tez.dag.api;
+
+import org.apache.hadoop.classification.InterfaceAudience.Public;
+import org.apache.hadoop.classification.InterfaceStability.Evolving;

tez-api/src/main/java/org/apache/tez/frameworkplugins/package-info.java

@@ -16,6 +16,10 @@
  * limitations under the License.
  */
 
+/**
+ * Pluggable framework services for the Tez runtime.
+ * Defines the client and AM framework service interfaces and utilities.
+ */
 @Public
 @Evolving
 package org.apache.tez.frameworkplugins;

tez-api/src/main/java/org/apache/tez/frameworkplugins/yarn/package-info.java

@@ -16,6 +16,10 @@
  * limitations under the License.
  */
 
+/**
+ * YARN-specific framework plugin implementations.
+ * Provides integration with YARN for resource management and application lifecycle.
+ */
 @Public
 @Evolving
 package org.apache.tez.frameworkplugins.yarn;

tez-api/src/main/java/org/apache/tez/frameworkplugins/zookeeper/package-info.java

@@ -16,6 +16,10 @@
  * limitations under the License.
  */
 
+/**
+ * ZooKeeper-based framework plugin implementations.
+ * Provides standalone and embedded ZooKeeper client services for Tez.
+ */
 @Public
 @Evolving
 package org.apache.tez.frameworkplugins.zookeeper;