Remove README and enhance inline code documentation

Co-authored-by: luabud <[email protected]>

Author: Copilot

DATAFRAME_DETECTION_README.md

@@ -36,6 +36,7 @@ export class DebugAdapterActivator implements IExtensionSingleActivationService
         this.disposables.push(
             this.debugService.registerDebugAdapterTrackerFactory(DebuggerTypeName, this.debuggerPromptFactory),
         );
+        // Register DataFrame tracker to monitor for dataframe variables and suggest Jupyter extension
         this.disposables.push(
             this.debugService.registerDebugAdapterTrackerFactory(DebuggerTypeName, this.dataFrameTrackerFactory),
         );

src/client/debugger/extension/adapter/activator.ts

@@ -19,36 +19,48 @@ import { IExtensions } from '../../../common/types';
 import { JUPYTER_EXTENSION_ID } from '../../../common/constants';
 
 /**
- * Debug adapter tracker that monitors for dataframe-like variables
- * and suggests installing the Jupyter extension when they are detected
- * but the Jupyter extension is not installed.
+ * Debug adapter tracker that monitors for dataframe-like variables during debugging sessions
+ * and suggests installing the Jupyter extension when they are detected but the Jupyter extension 
+ * is not installed. This helps users discover the data viewer functionality when working with
+ * dataframes without the Jupyter extension.
  */
 class DataFrameVariableTracker implements DebugAdapterTracker {
     private readonly extensions: IExtensions;
+    
+    /** Flag to ensure we only show the notification once per debug session to avoid spam */
     private hasNotifiedAboutJupyter = false;
 
-    // Types that are considered dataframe-like
+    /** 
+     * Known dataframe type patterns from popular Python data processing libraries.
+     * These patterns are matched against variable type strings in debug protocol responses.
+     */
     private readonly dataFrameTypes = [
-        'pandas.core.frame.DataFrame',
-        'pandas.DataFrame',
-        'polars.DataFrame',
-        'cudf.DataFrame',
-        'dask.dataframe.core.DataFrame',
-        'modin.pandas.DataFrame',
-        'vaex.dataframe.DataFrame',
-        'geopandas.geodataframe.GeoDataFrame',
+        'pandas.core.frame.DataFrame',  // Full pandas path
+        'pandas.DataFrame',             // Simplified pandas
+        'polars.DataFrame',             // Polars dataframes
+        'cudf.DataFrame',               // RAPIDS cuDF
+        'dask.dataframe.core.DataFrame', // Dask distributed dataframes
+        'modin.pandas.DataFrame',       // Modin pandas-compatible
+        'vaex.dataframe.DataFrame',     // Vaex out-of-core dataframes
+        'geopandas.geodataframe.GeoDataFrame', // GeoPandas geographic data
     ];
 
     constructor(_session: DebugSession, extensions: IExtensions) {
         this.extensions = extensions;
     }
 
+    /**
+     * Intercepts debug protocol messages to monitor for variable responses.
+     * When a variables response is detected, checks for dataframe-like objects.
+     * 
+     * @param message - Debug protocol message from the debug adapter
+     */
     public onDidSendMessage(message: DebugProtocol.Message): void {
         if (this.hasNotifiedAboutJupyter) {
             return; // Only notify once per debug session
         }
 
-        // Check if this is a variables response
+        // Check if this is a variables response from the debug protocol
         if ('type' in message && message.type === 'response' && 'command' in message && message.command === 'variables') {
             const response = message as unknown as DebugProtocol.VariablesResponse;
             if (response.success && response.body?.variables) {
@@ -57,13 +69,20 @@ class DataFrameVariableTracker implements DebugAdapterTracker {
         }
     }
 
+    /**
+     * Examines an array of debug variables to detect dataframe-like objects.
+     * Uses multiple detection strategies: type matching, value inspection, and name heuristics.
+     * 
+     * @param variables - Array of variables from debug protocol variables response
+     * @returns true if any dataframe-like variables were detected
+     */
     private checkForDataFrameVariables(variables: DebugProtocol.Variable[]): boolean {
-        // Check if any variable is a dataframe-like object
+        // Check if any variable is a dataframe-like object using multiple detection methods
         const hasDataFrame = variables.some((variable) =>
             this.dataFrameTypes.some((dfType) =>
                 variable.type?.includes(dfType) || 
                 variable.value?.includes(dfType) ||
-                // Also check if the variable name suggests it's a dataframe
+                // Also check if the variable name suggests it's a dataframe (common naming patterns)
                 (variable.name?.match(/^(df|data|dataframe)/i) && variable.type?.includes('pandas'))
             )
         );
@@ -75,8 +94,12 @@ class DataFrameVariableTracker implements DebugAdapterTracker {
         return hasDataFrame;
     }
 
+    /**
+     * Checks if the Jupyter extension is installed and shows notification if not.
+     * This is the core logic that determines whether the user needs the suggestion.
+     */
     private checkAndNotifyJupyterExtension(): void {
-        // Check if Jupyter extension is installed
+        // Check if Jupyter extension is installed using VS Code extension API
         const jupyterExtension = this.extensions.getExtension(JUPYTER_EXTENSION_ID);
 
         if (!jupyterExtension) {
@@ -85,6 +108,10 @@ class DataFrameVariableTracker implements DebugAdapterTracker {
         }
     }
 
+    /**
+     * Displays an information message suggesting Jupyter extension installation.
+     * Provides a direct action button to open the extension marketplace.
+     */
     private showJupyterInstallNotification(): void {
         const message = l10n.t('Install Jupyter extension to inspect dataframe objects in the data viewer.');
         const installAction = l10n.t('Install Jupyter Extension');
@@ -99,10 +126,22 @@ class DataFrameVariableTracker implements DebugAdapterTracker {
     }
 }
 
+/**
+ * Factory for creating DataFrameVariableTracker instances for debug sessions.
+ * This factory is registered with VS Code's debug adapter tracker system to
+ * automatically monitor all Python debug sessions for dataframe variables.
+ */
 @injectable()
 export class DataFrameTrackerFactory implements DebugAdapterTrackerFactory {
     constructor(@inject(IExtensions) private readonly extensions: IExtensions) {}
 
+    /**
+     * Creates a new DataFrameVariableTracker for each debug session.
+     * Each debug session gets its own tracker instance to maintain session-specific state.
+     * 
+     * @param session - The debug session that this tracker will monitor
+     * @returns A new DataFrameVariableTracker instance
+     */
     public createDebugAdapterTracker(session: DebugSession): ProviderResult<DebugAdapterTracker> {
         return new DataFrameVariableTracker(session, this.extensions);
     }

src/client/debugger/extension/adapter/dataFrameTracker.ts

@@ -64,6 +64,8 @@ export function registerTypes(serviceManager: IServiceManager): void {
         IOutdatedDebuggerPromptFactory,
         OutdatedDebuggerPromptFactory,
     );
+    // Register DataFrameTrackerFactory to monitor debug sessions for dataframe variables
+    // and suggest Jupyter extension installation when needed
     serviceManager.addSingleton<IDataFrameTrackerFactory>(
         IDataFrameTrackerFactory,
         DataFrameTrackerFactory,

src/client/debugger/extension/serviceRegistry.ts

@@ -19,8 +19,13 @@ export const IOutdatedDebuggerPromptFactory = Symbol('IOutdatedDebuggerPromptFac
 
 export interface IOutdatedDebuggerPromptFactory extends DebugAdapterTrackerFactory {}
 
+/** Symbol identifier for the DataFrameTrackerFactory service */
 export const IDataFrameTrackerFactory = Symbol('IDataFrameTrackerFactory');
 
+/** 
+ * Interface for debug adapter tracker factory that monitors dataframe variables
+ * and suggests Jupyter extension installation when dataframes are detected.
+ */
 export interface IDataFrameTrackerFactory extends DebugAdapterTrackerFactory {}
 
 export enum PythonPathSource {

src/client/debugger/extension/types.ts

@@ -12,6 +12,11 @@ import { IExtensions } from '../../../../client/common/types';
 import { JUPYTER_EXTENSION_ID } from '../../../../client/common/constants';
 import { DataFrameTrackerFactory } from '../../../../client/debugger/extension/adapter/dataFrameTracker';
 
+/**
+ * Test suite for DataFrame Tracker functionality.
+ * Tests the detection of dataframe variables in debug sessions and 
+ * Jupyter extension installation suggestions.
+ */
 suite('DataFrame Tracker', () => {
     let extensions: IExtensions;
     let mockExtensions: IExtensions;
@@ -29,6 +34,10 @@ suite('DataFrame Tracker', () => {
         expect(tracker).to.not.be.undefined;
     });
 
+    /**
+     * Test that pandas DataFrame variables are correctly detected
+     * from debug protocol variable responses.
+     */
     test('Should detect pandas DataFrame variable', () => {
         const mockSession = {} as any;
         const tracker = trackerFactory.createDebugAdapterTracker(mockSession) as any;
@@ -67,6 +76,10 @@ suite('DataFrame Tracker', () => {
         verify(mockExtensions.getExtension(JUPYTER_EXTENSION_ID)).once();
     });
 
+    /**
+     * Test that the tracker doesn't show notifications when Jupyter extension is already installed.
+     * This prevents unnecessary notifications for users who already have the data viewer available.
+     */
     test('Should not show notification if Jupyter extension is installed', () => {
         const mockSession = {} as any;
         const tracker = trackerFactory.createDebugAdapterTracker(mockSession) as any;
@@ -99,6 +112,10 @@ suite('DataFrame Tracker', () => {
         verify(mockExtensions.getExtension(JUPYTER_EXTENSION_ID)).once();
     });
 
+    /**
+     * Test that the tracker recognizes all supported dataframe types from various libraries.
+     * This ensures comprehensive coverage of popular dataframe implementations.
+     */
     test('Should detect various dataframe types', () => {
         // This test verifies that the dataFrameTypes array contains the expected types
         const expectedTypes = [
@@ -119,10 +136,14 @@ suite('DataFrame Tracker', () => {
         });
     });
 
+    /**
+     * Test that the tracker correctly rejects non-dataframe variables.
+     * This prevents false positives on regular variables like strings, numbers, etc.
+     */
     test('Should not detect non-dataframe variables', () => {
         const nonDataFrameTypes = [
             'str',
-            'int',
+            'int', 
             'list',
             'dict',
             'numpy.ndarray',