Add more javadoc, and adjust the used images for the stack frames.

Author: gzsombor

org.eclipse.jdt.debug.ui/ui/org/eclipse/jdt/internal/debug/ui/JDIModelPresentation.java

@@ -947,6 +947,11 @@ protected Image getDebugElementImage(Object element) {
 		return getDebugImage(image, flags);
 	}
 
+	/**
+	 * Returns the image associated with the given {@link IJavaStackFrame}, decorated with overlays, if the stack frame is out of sync
+	 * ({@link IJavaStackFrame#isOutOfSynch()} or synchronized ({@link IJavaStackFrame#isSynchronized()}). The base image is acquired from the
+	 * {@link StackFramePresentationProvider}.
+	 */
 	private Image getStackFrameImage(IJavaStackFrame stackFrame) {
 		var image = getStackFrameProvider().getStackFrameImage(stackFrame);
 		if (image == null) {
@@ -988,9 +993,8 @@ protected Image getExpressionImage(Object expression) {
 	}
 
 	/**
-	 * Returns the adornment flags for the given element.
-	 * These flags are used to render appropriate overlay
-	 * icons for the element.
+	 * Returns the adornment flags for the given element. These flags are used to render appropriate overlay icons for the element. It only supports
+	 * {@link IJavaThread} and {@link IJavaDebugTarget}, for other types it always returns 0.
 	 */
 	private int computeJDIAdornmentFlags(Object element) {
 		try {
@@ -2069,6 +2073,10 @@ protected JavaElementLabelProvider getJavaLabelProvider() {
 		return fJavaLabelProvider;
 	}
 
+	/**
+	 * @return a {@link StackFramePresentationProvider} which responsible to classify stack frames into categories and could provide category specific
+	 *         visual representations.
+	 */
 	private StackFramePresentationProvider getStackFrameProvider() {
 		if (fStackFrameProvider == null) {
 			fStackFrameProvider = new StackFramePresentationProvider();

org.eclipse.jdt.debug.ui/ui/org/eclipse/jdt/internal/debug/ui/StackFramePresentationProvider.java

@@ -1,5 +1,5 @@
 /*******************************************************************************
- * Copyright (c) 2021 Zsombor Gegesy.
+ * Copyright (c) 2021, 2025 Zsombor Gegesy and others.
  *
  * This program and the accompanying materials
  * are made available under the terms of the Eclipse Public License 2.0
@@ -36,14 +36,17 @@ public final class StackFramePresentationProvider implements IPropertyChangeList
 	public static final FilterManager PLATFORM_STACK_FRAMES = new FilterManager(IJDIPreferencesConstants.PREF_ACTIVE_PLATFORM_FRAME_FILTER_LIST, IJDIPreferencesConstants.PREF_INACTIVE_PLATFORM_FRAME_FILTER_LIST);
 	public static final FilterManager CUSTOM_STACK_FRAMES = new FilterManager(IJDIPreferencesConstants.PREF_ACTIVE_CUSTOM_FRAME_FILTER_LIST, IJDIPreferencesConstants.PREF_INACTIVE_CUSTOM_FRAME_FILTER_LIST);
 
+	/**
+	 * Class to decide if a particular class name is part of a list of classes and list of packages.
+	 */
 	static class Filters {
 		private final String[] filters;
 
 		Filters(String[] filters) {
 			this.filters = filters;
 		}
 
-		public boolean match(String fqcName) {
+		boolean match(String fqcName) {
 			for (String filter : filters) {
 				if (filter.endsWith("*")) { //$NON-NLS-1$
 					if (fqcName.startsWith(filter.substring(0, filter.length() - 1))) {
@@ -66,17 +69,26 @@ public boolean match(String fqcName) {
 
 	public StackFramePresentationProvider(IPreferenceStore store) {
 		this.store = store;
-		platform = getActivePlatformFilters(store);
-		custom = getActiveCustomFilters(store);
+		platform = createActivePlatformFilters(store);
+		custom = createActiveCustomFilters(store);
 		store.addPropertyChangeListener(this);
 		collapseStackFrames = store.getBoolean(IJDIPreferencesConstants.PREF_COLLAPSE_STACK_FRAMES);
 	}
 
-	private Filters getActivePlatformFilters(IPreferenceStore store) {
+	/**
+	 * Create a {@link Filters} object to decide if a class is part of the 'platform'. The platform definition is stored in the
+	 * {@link IPreferenceStore}. By default, this is the classes provided by the JVM.
+	 *
+	 */
+	private Filters createActivePlatformFilters(IPreferenceStore store) {
 		return new Filters(PLATFORM_STACK_FRAMES.getActiveList(store));
 	}
 
-	private Filters getActiveCustomFilters(IPreferenceStore store) {
+	/**
+	 * Create a {@link Filters} object to decide if a class is considered part of a custom, very important layer, which needs to be highlighted. This
+	 * definition is stored in the {@link IPreferenceStore}. By default, this is an empty list.
+	 */
+	private Filters createActiveCustomFilters(IPreferenceStore store) {
 		return new Filters(CUSTOM_STACK_FRAMES.getActiveList(store));
 	}
 
@@ -92,11 +104,9 @@ public ImageDescriptor getStackFrameImage(IJavaStackFrame frame) {
 		if (category != null) {
 			switch (category) {
 				case LIBRARY:
+				case SYNTHETIC:
+				case PLATFORM:
 					return JavaPluginImages.DESC_OBJS_JAR;
-				case TEST:
-					return JavaPluginImages.DESC_OBJS_TEST_ATTRIB;
-				case PRODUCTION:
-					return JavaPluginImages.DESC_OBJS_CFILE;
 				default:
 					break;
 			}
@@ -178,9 +188,9 @@ public void close() {
 	public void propertyChange(PropertyChangeEvent event) {
 		String prop = event.getProperty();
 		if (IJDIPreferencesConstants.PREF_ACTIVE_PLATFORM_FRAME_FILTER_LIST.equals(prop)) {
-			platform = getActivePlatformFilters(store);
+			platform = createActivePlatformFilters(store);
 		} else if (IJDIPreferencesConstants.PREF_ACTIVE_CUSTOM_FRAME_FILTER_LIST.equals(prop)) {
-			custom = getActiveCustomFilters(store);
+			custom = createActiveCustomFilters(store);
 		} else if (IJDIPreferencesConstants.PREF_COLLAPSE_STACK_FRAMES.equals(prop)) {
 			collapseStackFrames = (Boolean) event.getNewValue();
 		}

org.eclipse.jdt.debug.ui/ui/org/eclipse/jdt/internal/debug/ui/monitors/JavaThreadContentProvider.java

@@ -84,7 +84,7 @@ private int getFrameCount(IJavaThread thread) throws DebugException {
 	@Override
 	protected Object[] getChildren(Object parent, int index, int length, IPresentationContext context, IViewerUpdate monitor) throws CoreException {
 		if (parent instanceof GroupedStackFrame groupedFrame) {
-			return getChildren(groupedFrame, index, length);
+			return groupedFrame.getFramesAsArray(index, length);
 		}
 		IJavaThread thread = (IJavaThread)parent;
 		if (!thread.isSuspended()) {
@@ -93,10 +93,6 @@ protected Object[] getChildren(Object parent, int index, int length, IPresentati
 		return getElements(getChildren(thread), index, length);
 	}
 
-	private Object[] getChildren(GroupedStackFrame parent, int index, int length) {
-		return parent.getFramesAsArray(index, length);
-	}
-
 	protected Object[] getChildren(IJavaThread thread) {
 		try {
 			if (thread instanceof JDIThread) {
@@ -131,6 +127,12 @@ protected Object[] getChildren(IJavaThread thread) {
 		}
 	}
 
+	/**
+	 * Return the stack frames for the given {@link IJavaThread}. If stack frames grouping is not switched on, it just returns all the stack frames
+	 * reported by the JVM. When stack frame grouping enabled, all frames that are not considered as {@link Category#PRODUCTION},
+	 * {@link Category#TEST} and {@link Category#CUSTOM_FILTERED} grouped into {@link GroupedStackFrame}s, those are folded by default, but can be
+	 * expanded on demand by the user.
+	 */
 	private List<Object> getStackFrames(IJavaThread thread) throws DebugException {
 		var frames = thread.getStackFrames();
 		var stackFrameProvider = getStackFrameProvider();
@@ -228,6 +230,9 @@ private ISchedulingRule getThreadRule(IViewerUpdate[] updates) {
 		return null;
 	}
 
+	/**
+	 * @return a {@link StackFramePresentationProvider} to provide classification of the stack frames.
+	 */
 	private synchronized StackFramePresentationProvider getStackFrameProvider() {
 		if (stackFrameProvider == null) {
 			stackFrameProvider = new StackFramePresentationProvider();

org.eclipse.jdt.debug/model/org/eclipse/jdt/debug/core/IJavaStackFrame.java

@@ -42,7 +42,34 @@ public interface IJavaStackFrame extends IStackFrame, IJavaModifiers,
 	 *
 	 */
 	enum Category {
-		CUSTOM_FILTERED, SYNTHETIC, PLATFORM, TEST, PRODUCTION, LIBRARY, UNKNOWN
+		/**
+		 * The user specified a filter, can be used for highlighting specific, very important code layers.
+		 */
+		CUSTOM_FILTERED,
+		/**
+		 * The stack frame represents a synthetic function call, which is not based on actual Java source code.
+		 */
+		SYNTHETIC,
+		/**
+		 * Methods in classes that considered as platform, like code in 'java.*' packages.
+		 */
+		PLATFORM,
+		/**
+		 * Classes found in a test source folder in the project.
+		 */
+		TEST,
+		/**
+		 * Classes found in a non-test source folder in the project.
+		 */
+		PRODUCTION,
+		/**
+		 * Classes coming from a library, not from the actual project.
+		 */
+		LIBRARY,
+		/**
+		 * Classes with unknown origin.
+		 */
+		UNKNOWN
 	}
 
 	/**

org.eclipse.jdt.debug/model/org/eclipse/jdt/internal/debug/core/model/GroupedStackFrame.java

@@ -1,5 +1,5 @@
 /*******************************************************************************
- * Copyright (c) 2022 Zsombor Gegesy.
+ * Copyright (c) 2022, 2025 Zsombor Gegesy and others.
  *
  * This program and the accompanying materials
  * are made available under the terms of the Eclipse Public License 2.0
@@ -37,11 +37,17 @@ public int getFrameCount() {
 		return stackFrames.size();
 	}
 
+	/**
+	 * Return an array of child stack frames from the internally stored frames.
+	 */
 	public Object[] getFramesAsArray(int index, int length) {
 		var subList = stackFrames.subList(index, Math.min(index + length, stackFrames.size()));
 		return subList.isEmpty() ? null : subList.toArray();
 	}
 
+	/**
+	 * @return the top most frame from the stack frames grouped inside.
+	 */
 	public IJavaStackFrame getTopMostFrame() {
 		return !stackFrames.isEmpty() ? stackFrames.get(0) : null;
 	}