From 9323abc7885d81ce02ab7bc86459b35fda1ddffd Mon Sep 17 00:00:00 2001
From: dfsek <dfsek@protonmail.com>
Date: Mon, 26 Apr 2021 19:04:20 -0700
Subject: [PATCH] document Profiler

---
 .../com/dfsek/terra/profiler/Profiler.java    | 34 +++++++++++++++++++
 1 file changed, 34 insertions(+)

diff --git a/common/src/main/java/com/dfsek/terra/profiler/Profiler.java b/common/src/main/java/com/dfsek/terra/profiler/Profiler.java
index 090839d28..65560ad56 100644
--- a/common/src/main/java/com/dfsek/terra/profiler/Profiler.java
+++ b/common/src/main/java/com/dfsek/terra/profiler/Profiler.java
@@ -3,20 +3,54 @@ package com.dfsek.terra.profiler;
 import java.util.Map;
 
 public interface Profiler {
+    /**
+     * Push a frame to this profiler.
+     *
+     * @param frame ID of frame.
+     */
     void push(String frame);
 
+    /**
+     * Pop a frame from this profiler.
+     *
+     * @param frame ID of frame. Must match ID
+     *              at the top of the profiler stack.
+     */
     void pop(String frame);
 
+    /**
+     * Start profiling.
+     */
     void start();
 
+    /**
+     * Stop profiling.
+     */
     void stop();
 
+    /**
+     * Get the profiler data.
+     *
+     * @return Profiler data.
+     */
     Map<String, Timings> getTimings();
 
+    /**
+     * Return a {@link AutoCloseable} implementation that
+     * may be used in a try-with-resources statement for
+     * more intuitive profiling, with auto-push/pop.
+     *
+     * @param frame ID of frame.
+     * @return {@link AutoCloseable} implementation for use
+     * in try-with-resources.
+     */
     default ProfileFrame profile(String frame) {
         push(frame);
         return new ProfileFrame(() -> pop(frame));
     }
 
+    /**
+     * Clear the profiler data.
+     */
     void reset();
 }