all: add additional Javadoc to avoid nag

api/src/main/java/io/perfmark/PerfMark.java

@@ -170,6 +170,7 @@ public static void startTask(String taskName) {
    *
    * @param taskNameObject the name of the task.
    * @param taskNameFunction the function that will convert the taskNameObject to a taskName
+   * @param <T> the object type to be stringified
    * @since 0.22.0
    */
   public static <T> void startTask(T taskNameObject, StringFunction<? super T> taskNameFunction) {
@@ -197,10 +198,12 @@ public static void startTask(String taskName, String subTaskName) {
    *
    * <p>The returned closeable is meant to be used in a try-with-resources block. Callers should not
    * allow the returned closeable to be used outside of the try block that initiated the call.
+   * Unlike other closeables, it is not safe to call close() more than once.
    *
    * <p>This method is <strong>NOT API STABLE</strong>.
    *
    * @param taskName the name of the task.
+   * @return a closeable that must be closed at the end of the task
    * @since 0.23.0
    */
   @MustBeClosed
@@ -216,12 +219,15 @@ public static TaskCloseable traceTask(String taskName) {
    *
    * <p>This function has many more caveats than the {@link #traceTask(String)} that accept a
    * string. See the docs at {@link #attachTag(String, Object, StringFunction)} for a list of risks
-   * associated with passing a function.
+   * associated with passing a function.  Unlike other closeables, it is not safe to call close()
+   * more than once.
    *
    * <p>This method is <strong>NOT API STABLE</strong>.
    *
    * @param taskNameObject the name of the task.
    * @param taskNameFunction the function that will convert the taskNameObject to a taskName
+   * @param <T> the object type to be stringified
+   * @return a closeable that must be closed at the end of the task
    * @since 0.23.0
    */
   @MustBeClosed
@@ -571,6 +577,7 @@ public static void attachTag(String tagName, long tagValue0, long tagValue1) {
    * @param tagName The name of the value being attached
    * @param tagObject The tag object which will passed to the stringFunction.
    * @param stringFunction The function that will convert the object to
+   * @param <T> the type of tag object to be stringified
    * @since 0.22.0
    */
   public static <T> void attachTag(

impl/src/main/java/io/perfmark/impl/MarkHolderProvider.java

@@ -22,6 +22,8 @@ protected MarkHolderProvider() {}
 
   /**
    * To be removed in 0.26.0
+   *
+   * @return the new MarkHolder for the current thread.
    */
   @Deprecated
   public MarkHolder create() {
@@ -34,6 +36,8 @@ public MarkHolder create() {
    *
    * @param markHolderId the Unique ID associated with the Mark Holder.   This exists as a work around to Java's
    *                     thread ID, which does not guarantee they will not be reused.
+   * @return the new MarkHolder for the current thread.
+   * @since 0.24.0
    */
   public MarkHolder create(long markHolderId) {
     return create();

traceviewer/src/main/java/io/perfmark/traceviewer/package-info.java

@@ -14,6 +14,10 @@
  * limitations under the License.
  */
 
+/**
+ * The Trace View package reads the PerfMark recorded tasks, and converts them into the
+ * Chrome Trace Viewer format, bundled into a self-contained HTML page.
+ */
 @javax.annotation.CheckReturnValue
 @javax.annotation.ParametersAreNonnullByDefault
 package io.perfmark.traceviewer;

tracewriter/src/main/java/io/perfmark/tracewriter/package-info.java

@@ -14,6 +14,10 @@
  * limitations under the License.
  */
 
+/**
+ * The Trace Writer package reads the PerfMark recorded tasks, and converts them into the
+ * Chrome Trace Viewer format.
+ */
 @javax.annotation.CheckReturnValue
 @javax.annotation.ParametersAreNonnullByDefault
 package io.perfmark.tracewriter;