C0urante commented on code in PR #12937:
URL: https://github.com/apache/kafka/pull/12937#discussion_r1041131493


##########
connect/api/src/main/java/org/apache/kafka/connect/header/package-info.java:
##########
@@ -0,0 +1,20 @@
+/*
+ * 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.
+ */
+/**
+ * Provides API for application-defined metadata attached to Connect records.

Review Comment:
   Nit:
   ```suggestion
    * Provides an API for application-defined metadata attached to Connect 
records.
   ```



##########
connect/api/src/main/java/org/apache/kafka/connect/sink/package-info.java:
##########
@@ -0,0 +1,20 @@
+/*
+ * 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.
+ */
+/**
+ * Provides API for implementing connectors which write Kafka records to 
external applications.

Review Comment:
   Nits:
   
   ```suggestion
    * Provides an API for implementing connectors which write Kafka records to 
external applications,
    * also known as <i>sink connectors</i>.
   ```



##########
connect/api/src/main/java/org/apache/kafka/connect/connector/package-info.java:
##########
@@ -0,0 +1,20 @@
+/*
+ * 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.
+ */
+/**
+ * Provides pluggable interfaces for Connector and Task implementations.

Review Comment:
   Nit: is "pluggable" really necessary here? I've always used that term to 
identify parts of a code base or application that can be swapped out for 
something else, but only on an opt-in basis, and with a reasonable default 
available out of the box.
   
   Since there is no default `Connector` or `Task` implementation and it's 
required to write one in order to run a Kafka Connect connector, I'd opt to 
leave this bit out.
   
   Also worth noting that the `ConnectorContext` and `ConnectRecord` classes 
aren't really pluggable; they're defined by the Connect framework and users 
have no chance to swap in their own implementation (at least, not in a way that 
alters how they are used by the Connect framework).



##########
connect/api/src/main/java/org/apache/kafka/connect/transforms/package-info.java:
##########
@@ -0,0 +1,20 @@
+/*
+ * 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.
+ */
+/**
+ * Provides pluggable interface for altering data which is being moved by 
Connect.

Review Comment:
   Nit:
   
   ```suggestion
    * Provides a pluggable interface for altering data which is being moved by 
Connect.
   ```



##########
connect/api/src/main/java/org/apache/kafka/connect/transforms/predicates/package-info.java:
##########
@@ -0,0 +1,20 @@
+/*
+ * 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.
+ */
+/**
+ * Provides pluggable interface for describing when a {@link 
org.apache.kafka.connect.transforms.Transformation} should be applied to a 
record.

Review Comment:
   Nit:
   
   ```suggestion
    * Provides a pluggable interface for describing when a {@link 
org.apache.kafka.connect.transforms.Transformation} should be applied to a 
record.
   ```



##########
connect/api/src/main/java/org/apache/kafka/connect/connector/policy/package-info.java:
##########
@@ -0,0 +1,20 @@
+/*
+ * 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.
+ */
+/**
+ * Provides pluggable interfaces for connector security policies.

Review Comment:
   Maybe worth including an example that calls out the only interface currently 
in this package? Possibly something like this:
   ```suggestion
    * Provides pluggable interfaces for Connector and Task implementations. For 
example, the
    * {@link 
org.apache.kafka.connect.connector.policy.ConnectorClientConfigOverridePolicy 
ConnectorClientConfigOverridePolicy}
    * interface can be used to control which Kafka client properties can be 
overridden on a per-connector basis.
   ```



##########
connect/api/src/main/java/org/apache/kafka/connect/health/package-info.java:
##########
@@ -0,0 +1,20 @@
+/*
+ * 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.
+ */
+/**
+ * Provides interface for describing the state of a running Connect cluster.

Review Comment:
   We should be clear about who is going to be describing the cluster, and how 
this information can be used:
   
   ```suggestion
    * Provides an API for describing the state of a running Connect cluster.
    * The Connect runtime will instantiate members of this package and expose 
them to
    * components whose API gives them access to cluster information.
    * <p/>
    * For example, {@link org.apache.kafka.connect.rest.ConnectRestExtension 
REST extensions}
    * can use their {@link 
org.apache.kafka.connect.rest.ConnectRestExtensionContext#clusterState() 
context}
    * to learn about the state of the cluster.
   ```



##########
connect/api/src/main/java/org/apache/kafka/connect/errors/package-info.java:
##########
@@ -0,0 +1,20 @@
+/*
+ * 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.
+ */
+/**
+ * Provides common exception classes for Connect.

Review Comment:
   We should make it clear that these exception classes establish a two-way 
API, between connectors/tasks/etc. and the framework:
   ```suggestion
    * Provides common exception classes for Connect.
    * Some may be thrown by the Connect runtime if connectors, tasks, or other 
components perform invalid or failed operations,
    * and others may be thrown by connectors, tasks, or other components to 
signal failures to the Connect runtime.
   ```



##########
connect/api/src/main/java/org/apache/kafka/connect/source/package-info.java:
##########
@@ -0,0 +1,20 @@
+/*
+ * 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.
+ */
+/**
+ * Provides API for implementing connectors which read data from external 
applications into Kafka.

Review Comment:
   Same nits:
   
   ```suggestion
    * Provides an API for implementing connectors which read data from external 
applications into Kafka,
    * also known as <i>source connectors</i>.
   ```



##########
connect/api/src/main/java/org/apache/kafka/connect/rest/package-info.java:
##########
@@ -0,0 +1,20 @@
+/*
+ * 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.
+ */
+/**
+ * Provides pluggable interface for altering the behavior of the Connect REST 
API.

Review Comment:
   Nit:
   
   ```suggestion
    * Provides a pluggable interface for altering the behavior of the Connect 
REST API.
   ```



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: jira-unsubscr...@kafka.apache.org

For queries about this service, please contact Infrastructure at:
us...@infra.apache.org

Reply via email to