javadoc and comment updates/fixes

flatlaf-core/src/main/java/com/formdev/flatlaf/FlatClientProperties.java

@@ -22,6 +22,8 @@ import javax.swing.JComponent;
 import javax.swing.SwingConstants;
 
 /**
+ * Defines/documents own client properties used in FlatLaf.
+ *
  * @author Karl Tauber
  */
 public interface FlatClientProperties
@@ -293,10 +295,12 @@ public interface FlatClientProperties
 	String TABBED_PANE_MAXIMUM_TAB_WIDTH = "JTabbedPane.maximumTabWidth";
 
 	/**
-	 * Specifies the height of a tab.
+	 * Specifies the minimum height of a tab.
 	 * <p>
 	 * <strong>Component</strong> {@link javax.swing.JTabbedPane}<br>
 	 * <strong>Value type</strong> {@link java.lang.Integer}
+	 *
+	 * @see #TABBED_PANE_TAB_INSETS
 	 */
 	String TABBED_PANE_TAB_HEIGHT = "JTabbedPane.tabHeight";
 
@@ -306,6 +310,8 @@ public interface FlatClientProperties
 	 * <strong>Component</strong> {@link javax.swing.JTabbedPane}
 	 * or tab content components (see {@link javax.swing.JTabbedPane#setComponentAt(int, java.awt.Component)})<br>
 	 * <strong>Value type</strong> {@link java.awt.Insets}
+	 *
+	 * @see #TABBED_PANE_TAB_HEIGHT
 	 */
 	String TABBED_PANE_TAB_INSETS = "JTabbedPane.tabInsets";
 

flatlaf-core/src/main/java/com/formdev/flatlaf/UIDefaultsLoader.java

@@ -119,7 +119,7 @@ class UIDefaultsLoader
 					addonClassLoaders.add( addonClassLoader );
 			}
 
-			// load custom properties files (usually provides by applications)
+			// load custom properties files (usually provided by applications)
 			List<Object> customDefaultsSources = FlatLaf.getCustomDefaultsSources();
 			int size = (customDefaultsSources != null) ? customDefaultsSources.size() : 0;
 			for( int i = 0; i < size; i++ ) {

flatlaf-core/src/main/java/com/formdev/flatlaf/util/HiDPIUtils.java

@@ -134,7 +134,7 @@ public class HiDPIUtils
 		// - fractional scale factors result in fractional component Y device coordinates
 		// - fractional text Y device coordinates are rounded for horizontal lines of characters
 		// - maybe different rounding methods for drawing primitives (e.g. rectangle) and text
-		// - Java adds 0.5 to X/Y positions in before drawing string in BufferedTextPipe.enqueueGlyphList()
+		// - Java adds 0.5 to X/Y positions before drawing string in BufferedTextPipe.enqueueGlyphList()
 
 		// this is not the optimal solution, but works very good in most cases
 		// (tested with class FlatPaintingStringTest on Windows 10 with font "Segoe UI")

flatlaf-core/src/main/java/com/formdev/flatlaf/util/UIScale.java

@@ -36,9 +36,14 @@ import javax.swing.plaf.UIResource;
 import com.formdev.flatlaf.FlatSystemProperties;
 
 /**
- * Two scaling modes are supported for HiDPI displays:
+ * This class handles scaling in Swing UIs.
+ * It computes user scaling factor based on font size and
+ * provides methods to scale integer, float, {@link Dimension} and {@link Insets}.
+ * This class is look and feel independent.
+ * <p>
+ * Two scaling modes are supported by FlatLaf for HiDPI displays:
  *
- * 1) system scaling mode
+ * <h3>1) system scaling mode</h3>
  *
  * This mode is supported since Java 9 on all platforms and in some Java 8 VMs
  * (e.g. Apple and JetBrains). The JRE determines the scale factor per-display and
@@ -49,7 +54,7 @@ import com.formdev.flatlaf.FlatSystemProperties;
  * The scale factor may be different for each connected display.
  * The scale factor may change for a window when moving the window from one display to another one.
  *
- * 2) user scaling mode
+ * <h3>2) user scaling mode</h3>
  *
  * This mode is mainly for Java 8 compatibility, but is also used on Linux
  * or if the default font is changed.
@@ -85,6 +90,9 @@ public class UIScale
 
 	private static Boolean jreHiDPI;
 
+	/**
+	 * Returns whether system scaling is enabled.
+	 */
 	public static boolean isSystemScalingEnabled() {
 		if( jreHiDPI != null )
 			return jreHiDPI;
@@ -112,10 +120,16 @@ public class UIScale
 		return jreHiDPI;
 	}
 
+	/**
+	 * Returns the system scale factor for the given graphics context.
+	 */
 	public static double getSystemScaleFactor( Graphics2D g ) {
 		return isSystemScalingEnabled() ? getSystemScaleFactor( g.getDeviceConfiguration() ) : 1;
 	}
 
+	/**
+	 * Returns the system scale factor for the given graphics configuration.
+	 */
 	public static double getSystemScaleFactor( GraphicsConfiguration gc ) {
 		return (isSystemScalingEnabled() && gc != null) ? gc.getDefaultTransform().getScaleX() : 1;
 	}
@@ -297,11 +311,17 @@ public class UIScale
 		}
 	}
 
+	/**
+	 * Returns the user scale factor.
+	 */
 	public static float getUserScaleFactor() {
 		initialize();
 		return scaleFactor;
 	}
 
+	/**
+	 * Sets the user scale factor.
+	 */
 	private static void setUserScaleFactor( float scaleFactor ) {
 		if( scaleFactor <= 1f )
 			scaleFactor = 1f;
@@ -318,40 +338,65 @@ public class UIScale
 			changeSupport.firePropertyChange( "userScaleFactor", oldScaleFactor, scaleFactor );
 	}
 
+	/**
+	 * Multiplies the given value by the user scale factor.
+	 */
 	public static float scale( float value ) {
 		initialize();
 		return (scaleFactor == 1) ? value : (value * scaleFactor);
 	}
 
+	/**
+	 * Multiplies the given value by the user scale factor and rounds the result.
+	 */
 	public static int scale( int value ) {
 		initialize();
 		return (scaleFactor == 1) ? value : Math.round( value * scaleFactor );
 	}
 
 	/**
-	 * Similar as scale(int) but always "rounds down".
+	 * Similar as {@link #scale(int)} but always "rounds down".
+	 * <p>
+	 * For use in special cases. {@link #scale(int)} is the preferred method.
 	 */
 	public static int scale2( int value ) {
 		initialize();
 		return (scaleFactor == 1) ? value : (int) (value * scaleFactor);
 	}
 
+	/**
+	 * Divides the given value by the user scale factor.
+	 */
 	public static float unscale( float value ) {
 		initialize();
 		return (scaleFactor == 1f) ? value : (value / scaleFactor);
 	}
 
+	/**
+	 * Divides the given value by the user scale factor and rounds the result.
+	 */
 	public static int unscale( int value ) {
 		initialize();
 		return (scaleFactor == 1f) ? value : Math.round( value / scaleFactor );
 	}
 
+	/**
+	 * If user scale factor is not 1, scale the given graphics context by invoking
+	 * {@link Graphics2D#scale(double, double)} with user scale factor.
+	 */
 	public static void scaleGraphics( Graphics2D g ) {
 		initialize();
 		if( scaleFactor != 1f )
 			g.scale( scaleFactor, scaleFactor );
 	}
 
+	/**
+	 * Scales the given dimension with the user scale factor.
+	 * <p>
+	 * If user scale factor is 1, then the given dimension is simply returned.
+	 * Otherwise a new instance of {@link Dimension} or {@link DimensionUIResource}
+	 * is returned, depending on whether the passed dimension implements {@link UIResource}.
+	 */
 	public static Dimension scale( Dimension dimension ) {
 		initialize();
 		return (dimension == null || scaleFactor == 1f)
@@ -361,6 +406,13 @@ public class UIScale
 				: new Dimension          ( scale( dimension.width ), scale( dimension.height ) ));
 	}
 
+	/**
+	 * Scales the given insets with the user scale factor.
+	 * <p>
+	 * If user scale factor is 1, then the given insets is simply returned.
+	 * Otherwise a new instance of {@link Insets} or {@link InsetsUIResource}
+	 * is returned, depending on whether the passed dimension implements {@link UIResource}.
+	 */
 	public static Insets scale( Insets insets ) {
 		initialize();
 		return (insets == null || scaleFactor == 1f)

flatlaf-extras/src/main/java/com/formdev/flatlaf/extras/components/FlatTabbedPane.java

@@ -164,14 +164,16 @@ public class FlatTabbedPane
 
 
 	/**
-	 * Returns the height of a tab.
+	 * Returns the minimum height of a tab.
 	 */
 	public int getTabHeight() {
 		return getClientPropertyInt( TABBED_PANE_TAB_HEIGHT, "TabbedPane.tabHeight" );
 	}
 
 	/**
-	 * Specifies the height of a tab.
+	 * Specifies the minimum height of a tab.
+	 *
+	 * @see #setTabInsets(Insets)
 	 */
 	public void setTabHeight( int tabHeight ) {
 		putClientProperty( TABBED_PANE_TAB_HEIGHT, (tabHeight >= 0) ? tabHeight : null );
@@ -187,6 +189,8 @@ public class FlatTabbedPane
 
 	/**
 	 * Specifies the insets of a tab.
+	 *
+	 * @see #setTabHeight(int)
 	 */
 	public void setTabInsets( Insets tabInsets ) {
 		putClientProperty( TABBED_PANE_TAB_INSETS, tabInsets );
@@ -203,6 +207,8 @@ public class FlatTabbedPane
 
 	/**
 	 * Specifies the insets of the tab at the given tab index.
+	 *
+	 * @see #setTabHeight(int)
 	 */
 	public void setTabInsets( int tabIndex, Insets tabInsets ) {
 		JComponent c = (JComponent) getComponentAt( tabIndex );