From 432de76b57b12601c553034e64f4720c3a64c4f2 Mon Sep 17 00:00:00 2001
From: Brice Dutheil <brice.dutheil@gmail.com>
Date: Thu, 9 Jun 2022 16:07:22 +0200
Subject: [PATCH] docs(flamegraph): FrameColorProvider / FrameFontProvider

---
 .../flamegraph/FrameColorProvider.java        | 33 ++++++++++++++++---
 .../flamegraph/FrameFontProvider.java         |  7 +++-
 2 files changed, 34 insertions(+), 6 deletions(-)

diff --git a/fireplace-swing/src/main/java/io/github/bric3/fireplace/flamegraph/FrameColorProvider.java b/fireplace-swing/src/main/java/io/github/bric3/fireplace/flamegraph/FrameColorProvider.java
index 28d37855..2d3c5a1d 100644
--- a/fireplace-swing/src/main/java/io/github/bric3/fireplace/flamegraph/FrameColorProvider.java
+++ b/fireplace-swing/src/main/java/io/github/bric3/fireplace/flamegraph/FrameColorProvider.java
@@ -28,17 +28,28 @@
 import static io.github.bric3.fireplace.flamegraph.FrameRenderingFlags.isHighlighting;
 import static io.github.bric3.fireplace.flamegraph.FrameRenderingFlags.isHovered;
 
+/**
+ * Strategy for choosing the colors of a frame.
+ *
+ * @param <T> The type of the frame node (depends on the source of profiling data).
+ */
 public interface FrameColorProvider<T> {
     class ColorModel {
         public Color background;
         public Color foreground;
 
-        public ColorModel(Color background, Color foreground) {
+        /**
+         * Data-structure that hold the computed colors for a frame.
+         *
+         * @param background The background color of the frame.
+         * @param foreground The foreground color of the frame.
+         */
+        ColorModel(Color background, Color foreground) {
             this.background = background;
             this.foreground = foreground;
         }
 
-        public ColorModel set(Color background, Color foreground) {
+        ColorModel set(Color background, Color foreground) {
             this.background = background;
             this.foreground = foreground;
             return this;
@@ -49,10 +60,22 @@ public ColorModel copy() {
         }
     }
 
+    /**
+     * Returns the color model for the given <code>frame</code> according to the given <code>flags</code>.
+     *
+     * <p>
+     *     An implementation may choose to return the same instance of color model
+     *     for all frames to save allocations.
+     * </p>
+     *
+     * @param frame The frame
+     * @param flags The flags
+     * @return The color model for this frame
+     */
     ColorModel getColors(FrameBox<T> frame, int flags) ;
 
-    static <T> FrameColorProvider<T> defaultColorProvider(Function<FrameBox<T>, Color> frameColorFunction) {
-        Objects.requireNonNull(frameColorFunction, "frameColorFunction");
+    static <T> FrameColorProvider<T> defaultColorProvider(Function<FrameBox<T>, Color> frameBaseColorFunction) {
+        Objects.requireNonNull(frameBaseColorFunction, "frameColorFunction");
         return new FrameColorProvider<T>() {
             /**
              * The color used to draw frames that are highlighted.
@@ -63,7 +86,7 @@ static <T> FrameColorProvider<T> defaultColorProvider(Function<FrameBox<T>, Colo
 
             @Override
             public ColorModel getColors(FrameBox<T> frame, int flags) {
-                Color baseBackgroundColor = frameColorFunction.apply(frame);
+                Color baseBackgroundColor = frameBaseColorFunction.apply(frame);
                 Color backgroundColor = baseBackgroundColor;
 
                 if (isFocusing(flags) && !isFocusedFrame(flags)) {
diff --git a/fireplace-swing/src/main/java/io/github/bric3/fireplace/flamegraph/FrameFontProvider.java b/fireplace-swing/src/main/java/io/github/bric3/fireplace/flamegraph/FrameFontProvider.java
index 02da7c6a..d154bf77 100644
--- a/fireplace-swing/src/main/java/io/github/bric3/fireplace/flamegraph/FrameFontProvider.java
+++ b/fireplace-swing/src/main/java/io/github/bric3/fireplace/flamegraph/FrameFontProvider.java
@@ -21,6 +21,11 @@
 import static io.github.bric3.fireplace.flamegraph.FrameRenderingFlags.isHighlightedFrame;
 import static io.github.bric3.fireplace.flamegraph.FrameRenderingFlags.isPartialFrame;
 
+/**
+ * Strategy for choosing the font of a frame.
+ *
+ * @param <T> The type of the frame node (depends on the source of profiling data).
+ */
 public interface FrameFontProvider<T> {
 
     /**
@@ -31,7 +36,7 @@ public interface FrameFontProvider<T> {
      * parameter is <code>null</code>. Possibly honoring the <code>flags</code>.
      * </p>
      *
-     * @param frame The frame to get the font for, can be null.
+     * @param frame The frame to get the font for, can be <code>null</code>.
      * @param flags The flags
      * @return The font to use for the frame and flags.
      */