Merge pull request #2009 from newrelic/update-javadoc-comments

Update Javadoc comments for @trace API

newrelic-api/src/main/java/com/newrelic/api/agent/Trace.java

@@ -47,6 +47,10 @@
 
     /**
      * Sets the metric name for this tracer. If unspecified, the class / method name will be used.
+     *
+     * When using both nameTransaction and metricName, nameTransaction will take precedence and the
+     * transaction will use the name from the underlying tracer (typically class/method), rather than the
+     * custom name set by metricName. It is recommended to use one or the other depending on naming preferences.
      * 
      * @return The metric name for this tracer.
      * @since 1.3.0
@@ -75,6 +79,10 @@
 
     /**
      * Names the current transaction using this tracer's metric name.
+     *
+     * When using both nameTransaction and metricName, nameTransaction will take precedence and the
+     * transaction will use the name from the underlying tracer (typically class/method), rather than the
+     * custom name set by metricName. It is recommended to use one or the other depending on naming preferences.
      * 
      * @return True if this traced method should be used to name the transaction, else false.
      * @since 3.1.0