Update LoggerBuilder, MeterBuilder, TracerBuilder javadoc (open-telem…

…etry#5050)

api/all/src/main/java/io/opentelemetry/api/metrics/MeterBuilder.java

@@ -8,22 +8,28 @@
 /**
  * Builder class for creating {@link Meter} instances.
  *
+ * <p>{@link Meter}s are identified by their scope name, version, and schema URL. These identifying
+ * fields, along with attributes, combine to form the instrumentation scope, which is attached to
+ * all metrics produced by the {@link Meter}.
+ *
  * @since 1.10.0
  */
 public interface MeterBuilder {
 
   /**
-   * Assigns an OpenTelemetry schema URL to the resulting Meter.
+   * Set the scope schema URL of the resulting {@link Meter}. Schema URL is part of {@link Meter}
+   * identity.
    *
-   * @param schemaUrl The URL of the OpenTelemetry schema being used by this instrumentation scope.
+   * @param schemaUrl The schema URL.
    * @return this
    */
   MeterBuilder setSchemaUrl(String schemaUrl);
 
   /**
-   * Assigns a version to the instrumentation scope that is using the resulting Meter.
+   * Sets the instrumentation scope version of the resulting {@link Meter}. Version is part of
+   * {@link Meter} identity.
    *
-   * @param instrumentationScopeVersion The version of the instrumentation scope.
+   * @param instrumentationScopeVersion The instrumentation scope version.
    * @return this
    */
   MeterBuilder setInstrumentationVersion(String instrumentationScopeVersion);

api/all/src/main/java/io/opentelemetry/api/trace/TracerBuilder.java

@@ -8,22 +8,28 @@
 /**
  * Builder class for creating {@link Tracer} instances.
  *
+ * <p>{@link Tracer}s are identified by their scope name, version, and schema URL. These identifying
+ * fields, along with attributes, combine to form the instrumentation scope, which is attached to
+ * all spans produced by the {@link Tracer}.
+ *
  * @since 1.4.0
  */
 public interface TracerBuilder {
 
   /**
-   * Assign an OpenTelemetry schema URL to the resulting Tracer.
+   * Set the scope schema URL of the resulting {@link Tracer}. Schema URL is part of {@link Tracer}
+   * identity.
    *
-   * @param schemaUrl The URL of the OpenTelemetry schema being used by this instrumentation scope.
+   * @param schemaUrl The schema URL.
    * @return this
    */
   TracerBuilder setSchemaUrl(String schemaUrl);
 
   /**
-   * Assign a version to the instrumentation scope that is using the resulting Tracer.
+   * Sets the instrumentation scope version of the resulting {@link Tracer}. Version is part of
+   * {@link Tracer} identity.
    *
-   * @param instrumentationScopeVersion The version of the instrumentation scope.
+   * @param instrumentationScopeVersion The instrumentation scope version.
    * @return this
    */
   TracerBuilder setInstrumentationVersion(String instrumentationScopeVersion);

api/logs/src/main/java/io/opentelemetry/api/logs/LoggerBuilder.java

@@ -5,7 +5,13 @@
 
 package io.opentelemetry.api.logs;
 
-/** Builder class for creating {@link Logger} instances. */
+/**
+ * Builder class for creating {@link Logger} instances.
+ *
+ * <p>{@link Logger}s are identified by their scope name, version, and schema URL. These identifying
+ * fields, along with attributes, combine to form the instrumentation scope, which is attached to
+ * all log records produced by the {@link Logger}.
+ */
 public interface LoggerBuilder {
 
   /**
@@ -23,25 +29,27 @@ public interface LoggerBuilder {
   LoggerBuilder setEventDomain(String eventDomain);
 
   /**
-   * Assign an OpenTelemetry schema URL to the resulting {@link Logger}.
+   * Set the scope schema URL of the resulting {@link Logger}. Schema URL is part of {@link Logger}
+   * identity.
    *
-   * @param schemaUrl the URL of the OpenTelemetry schema being used by this instrumentation scope
+   * @param schemaUrl The schema URL.
    * @return this
    */
   LoggerBuilder setSchemaUrl(String schemaUrl);
 
   /**
-   * Assign a version to the instrumentation scope that is using the resulting {@link Logger}.
+   * Sets the instrumentation scope version of the resulting {@link Logger}. Version is part of
+   * {@link Logger} identity.
    *
-   * @param instrumentationScopeVersion the version of the instrumentation scope
+   * @param instrumentationScopeVersion The instrumentation scope version.
    * @return this
    */
   LoggerBuilder setInstrumentationVersion(String instrumentationScopeVersion);
 
   /**
    * Gets or creates a {@link Logger} instance.
    *
-   * @return a logger instance configured with the provided options
+   * @return a {@link Logger} instance configured with the provided options.
    */
   Logger build();
 }