Merge pull request #51257 from holly-cummins/correct-javadoc

Correct javadoc and add javadoc for service config

Author: holly-cummins

core/deployment/src/main/java/io/quarkus/deployment/builditem/DevServicesResultBuildItem.java

@@ -89,15 +89,15 @@ public static <T extends Startable> OwnedServiceBuilder<T> owned() {
     }
 
     /**
-     * @deprecated use DevServicesResultBuildItem.builder() instead
+     * @deprecated use {@link DevServicesResultBuildItem#owned()} or {@link DevServicesResultBuildItem#discovered()} instead
      */
     @Deprecated
     public DevServicesResultBuildItem(String name, String containerId, Map<String, String> config) {
         this(name, null, containerId, config);
     }
 
     /**
-     * @deprecated use DevServicesResultBuildItem.builder() instead
+     * @deprecated use {@link DevServicesResultBuildItem#owned()} or {@link DevServicesResultBuildItem#discovered()} instead
      */
     @Deprecated
     public DevServicesResultBuildItem(String name, String description, String containerId, Map<String, String> config) {
@@ -114,7 +114,7 @@ public DevServicesResultBuildItem(String name, String description, String contai
     }
 
     /**
-     * @deprecated use DevServicesResultBuildItem.builder() instead
+     * @deprecated use {@link DevServicesResultBuildItem#owned()} or {@link DevServicesResultBuildItem#discovered()} instead
      */
     @Deprecated
     public DevServicesResultBuildItem(String name,
@@ -161,6 +161,11 @@ public String getServiceName() {
         return serviceName;
     }
 
+    /**
+     * {@see OwnedServiceBuilder#serviceConfig}
+     *
+     * @return the identifying configuration
+     */
     public Object getServiceConfig() {
         return serviceConfig;
     }
@@ -290,6 +295,20 @@ public OwnedServiceBuilder<T> serviceName(String serviceName) {
             return this;
         }
 
+        /**
+         * Declares the configuration of this service. This is used as a uniqueness identifier to establish whether
+         * services should be restarted, for example between live reloads.
+         * Usually it would be the config object passed in to the build step,
+         * but if the reuse semantics are different, it could be a subset or superset of that object.
+         * If you want your service to be restarted when the config is different, and re-used otherwise, pass
+         * through your config. If you want it to be always restarted on live reloads, you could pass through something like a
+         * random number. If you want the service to never be restarted, you could pass through a constant.
+         *
+         * @param serviceConfig an object with defining characteristics of the service. It will be reflectively compared to the
+         *        previous configuration.
+         * @return a builder, for chaining
+         */
+
         public OwnedServiceBuilder<T> serviceConfig(Object serviceConfig) {
             this.serviceConfig = serviceConfig;
             return this;