Improve documentation and consistency

felixfbecker · felixfbecker · commit ad922e4ec357 · 2015-12-30T12:11:50.000+01:00
diff --git a/src/phpDebug.ts b/src/phpDebug.ts
@@ -67,21 +67,21 @@ class PhpDebugSession extends vscode.DebugSession {
     private _connections = new Map<number, xdebug.Connection>();
     /** The first connection we receive */
     private _mainConnection: xdebug.Connection = null;
-    /** Gets set to true after _runOrStopOnEntry is called the first time, which means all exceptions etc. are set */
+    /** Gets set to true after _runOrStopOnEntry is called the first time and means all exceptions etc. are set */
     private _initialized = false;
     /** A map of file URIs to lines: breakpoints received from VS Code */
     private _breakpoints = new Map<string, number[]>();
     /** Gets set after a setExceptionBreakpointsRequest */
     private _breakOnExceptions: boolean;
     /** A counter for unique stackframe IDs */
     private _stackFrameIdCounter = 1;
-    /** Maps a stackframe ID to its connection and the level inside the stacktrace for scope requests */
+    /** A map from unique stackframe IDs (even across connections) to XDebug stackframes */
     private _stackFrames = new Map<number, xdebug.StackFrame>();
-    /** A counter for unique context and variable IDs (as the content of a scope is requested by a VariableRequest from VS Code) */
+    /** A counter for unique context, property and eval result properties (as these are all requested by a VariableRequest from VS Code) */
     private _variableIdCounter = 1;
-    /** A map that maps a unique VS Code variable ID to an XDebug contextId and an XDebug stackframe */
+    /** A map from unique VS Code variable IDs to an XDebug contexts */
     private _contexts = new Map<number, xdebug.Context>();
-    /** A map that maps a unique VS Code variable ID to an XDebug scope and an XDebug long variable name */
+    /** A map from unique VS Code variable IDs to a XDebug properties */
     private _properties = new Map<number, xdebug.Property>();
     /** A map from unique VS Code variable IDs to XDebug eval result properties, because property children returned from eval commands are always inlined */
     private _evalResultProperties = new Map<number, xdebug.EvalResultProperty>();
@@ -114,9 +114,9 @@ class PhpDebugSession extends vscode.DebugSession {
                     // raise default of 32
                     .then(() => connection.sendFeatureSetCommand('max_children', '9999'))
                     // restore all breakpoints for the new connection
-                    .then(() => Promise.all(Array.from(this._breakpoints).map(([file, lines]) =>
+                    .then(() => Promise.all(Array.from(this._breakpoints).map(([fileUri, lines]) =>
                         Promise.all(lines.map(line =>
-                            connection.sendBreakpointSetCommand({type: 'line', file, line})
+                            connection.sendBreakpointSetCommand({type: 'line', fileUri, line})
                         ))
                     )))
                     // restore exception breakpoint settings for the new connection
@@ -217,7 +217,7 @@ class PhpDebugSession extends vscode.DebugSession {
 
     /** This is called for each source file that has breakpoints with all the breakpoints in that file and whenever these change. */
     protected setBreakPointsRequest(response: VSCodeDebugProtocol.SetBreakpointsResponse, args: VSCodeDebugProtocol.SetBreakpointsArguments) {
-        const file = path2uri(args.source.path);
+        const fileUri = path2uri(args.source.path);
         const connections = Array.from(this._connections.values());
         let breakpoints: vscode.Breakpoint[];
         let breakpointsSetPromise: Promise<any>;
@@ -232,12 +232,12 @@ class PhpDebugSession extends vscode.DebugSession {
                 connection.sendBreakpointListCommand()
                     .then(response => Promise.all(
                         response.breakpoints
-                            .filter(breakpoint => breakpoint.type === 'line' && breakpoint.fileUri === file)
+                            .filter(breakpoint => breakpoint.type === 'line' && breakpoint.fileUri === fileUri)
                             .map(breakpoint => breakpoint.remove())
                     ))
                     // set them
                     .then(() => Promise.all(args.lines.map(line =>
-                        connection.sendBreakpointSetCommand({type: 'line', file, line})
+                        connection.sendBreakpointSetCommand({type: 'line', fileUri, line})
                             .then(xdebugResponse => {
                                 // only capture each breakpoint once (for the main connection)
                                 if (connection === this._mainConnection) {
@@ -257,7 +257,7 @@ class PhpDebugSession extends vscode.DebugSession {
         breakpointsSetPromise
             .then(() => {
                 response.body = {breakpoints};
-                this._breakpoints.set(file, args.lines);
+                this._breakpoints.set(fileUri, args.lines);
                 this.sendResponse(response);
             })
             .catch(error => {
diff --git a/src/xdebugConnection.ts b/src/xdebugConnection.ts
@@ -33,6 +33,7 @@ export class InitPacket {
     }
 }
 
+/** Error class for errors returned from XDebug */
 export class XDebugError extends Error {
     code: number;
     constructor(message: string, code: number) {
@@ -339,6 +340,7 @@ export class PropertyGetResponse extends Response {
     }
 }
 
+/** class for properties returned from eval commands. These don't have a full name or an ID, but have all children already inlined. */
 export class EvalResultProperty extends BaseProperty {
     children: EvalResultProperty[];
     constructor(propertyNode: Element) {
@@ -349,7 +351,9 @@ export class EvalResultProperty extends BaseProperty {
     }
 }
 
+/** The response to an eval command */
 export class EvalResponse extends Response {
+    /** the result of the expression, if there was any */
     result: EvalResultProperty;
     constructor(document: XMLDocument, connection: Connection) {
         super(document, connection);
@@ -359,7 +363,9 @@ export class EvalResponse extends Response {
     }
 }
 
+/** The response to an feature_set command */
 export class FeatureSetResponse extends Response {
+    /** the feature that was set */
     feature: string;
     constructor(document: XMLDocument, connection: Connection) {
         super(document, connection);
@@ -538,12 +544,18 @@ export class Connection extends DbgpConnection {
     // ---------------------------- breakpoints ------------------------------------
 
     /**
-     * Sends a breakpoint_set command that sets a line breakpoint.
+     * Sends a breakpoint_set command that sets a breakpoint.
+     * @param {object} breakpoint
+     * @param {string} breakpoint.type - the type of breakpoint. Can be 'line' or 'exception'
+     * @param {string} [breakpoint.fileUri] - the file URI to break on if type is 'line'
+     * @param {number} [breakpoint.line] - the line to break on if type is 'line'
+     * @param {string} [breakpoint.exception] - the exception class name to break on if type is 'exception'
+     * @returns Promise.<BreakpointSetResponse>
      */
-    public sendBreakpointSetCommand(breakpoint: {type: string, file?: string, line?: number, exception?: string}): Promise<BreakpointSetResponse> {
+    public sendBreakpointSetCommand(breakpoint: {type: string, fileUri?: string, line?: number, exception?: string}): Promise<BreakpointSetResponse> {
         let args = `-t ${breakpoint.type} `;
         if (breakpoint.type === 'line') {
-            args += `-f ${breakpoint.file} -n ${breakpoint.line}`;
+            args += `-f ${breakpoint.fileUri} -n ${breakpoint.line}`;
         } else if (breakpoint.type === 'exception') {
             args += `-x ${breakpoint.exception}`;
         } else {
@@ -552,39 +564,46 @@ export class Connection extends DbgpConnection {
         return this._enqueueCommand('breakpoint_set', args).then(document => new BreakpointSetResponse(document, this));
     }
 
+    /** sends a breakpoint_list command */
     public sendBreakpointListCommand(): Promise<BreakpointListResponse> {
         return this._enqueueCommand('breakpoint_list').then(document => new BreakpointListResponse(document, this));
     }
 
+    /** sends a breakpoint_remove command */
     public sendBreakpointRemoveCommand(breakpoint: Breakpoint): Promise<Response> {
         return this._enqueueCommand('breakpoint_remove', `-d ${breakpoint.id}`).then(document => new Response(document, this));
     }
 
     // ----------------------------- continuation ---------------------------------
 
+    /** sends a run command */
     public sendRunCommand(): Promise<StatusResponse> {
         return this._enqueueCommand('run').then(document => new StatusResponse(document, this));
     }
 
+    /** sends a step_into command */
     public sendStepIntoCommand(): Promise<StatusResponse> {
         return this._enqueueCommand('step_into').then(document => new StatusResponse(document, this));
     }
 
+    /** sends a step_over command */
     public sendStepOverCommand(): Promise<StatusResponse> {
         return this._enqueueCommand('step_over').then(document => new StatusResponse(document, this));
     }
 
+    /** sends a step_out command */
     public sendStepOutCommand(): Promise<StatusResponse> {
         return this._enqueueCommand('step_out').then(document => new StatusResponse(document, this));
     }
 
+    /** sends a stop command */
     public sendStopCommand(): Promise<StatusResponse> {
         return this._enqueueCommand('stop').then(document => new StatusResponse(document, this));
     }
 
     // ------------------------------ stack ----------------------------------------
 
-    /** Sends a stack_get request */
+    /** Sends a stack_get command */
     public sendStackGetCommand(): Promise<StackGetResponse> {
         return this._enqueueCommand('stack_get').then(document => new StackGetResponse(document, this));
     }
@@ -608,6 +627,7 @@ export class Connection extends DbgpConnection {
 
     // ------------------------------- eval -----------------------------------------
 
+    /** sends an eval command */
     public sendEvalCommand(expression: string): Promise<EvalResponse> {
         return this._enqueueCommand('eval', null, expression).then(document => new EvalResponse(document, this));
     }

Original file line number	Diff line number	Diff line change
`@@ -33,6 +33,7 @@ export class InitPacket {`
`33`	`33`	`}`
`34`	`34`	`}`
`35`	`35`
	`36`	`+/** Error class for errors returned from XDebug */`
`36`	`37`	`export class XDebugError extends Error {`
`37`	`38`	`code: number;`
`38`	`39`	`constructor(message: string, code: number) {`
`@@ -339,6 +340,7 @@ export class PropertyGetResponse extends Response {`
`339`	`340`	`}`
`340`	`341`	`}`
`341`	`342`
	`343`	`+/** class for properties returned from eval commands. These don't have a full name or an ID, but have all children already inlined. */`
`342`	`344`	`export class EvalResultProperty extends BaseProperty {`
`343`	`345`	`children: EvalResultProperty[];`
`344`	`346`	`constructor(propertyNode: Element) {`
`@@ -349,7 +351,9 @@ export class EvalResultProperty extends BaseProperty {`
`349`	`351`	`}`
`350`	`352`	`}`
`351`	`353`
	`354`	`+/** The response to an eval command */`
`352`	`355`	`export class EvalResponse extends Response {`
	`356`	`+ /** the result of the expression, if there was any */`
`353`	`357`	`result: EvalResultProperty;`
`354`	`358`	`constructor(document: XMLDocument, connection: Connection) {`
`355`	`359`	`super(document, connection);`
`@@ -359,7 +363,9 @@ export class EvalResponse extends Response {`
`359`	`363`	`}`
`360`	`364`	`}`
`361`	`365`
	`366`	`+/** The response to an feature_set command */`
`362`	`367`	`export class FeatureSetResponse extends Response {`
	`368`	`+ /** the feature that was set */`
`363`	`369`	`feature: string;`
`364`	`370`	`constructor(document: XMLDocument, connection: Connection) {`
`365`	`371`	`super(document, connection);`
`@@ -538,12 +544,18 @@ export class Connection extends DbgpConnection {`
`538`	`544`	`// ---------------------------- breakpoints ------------------------------------`
`539`	`545`
`540`	`546`	`/**`
`541`		`- * Sends a breakpoint_set command that sets a line breakpoint.`
	`547`	`+ * Sends a breakpoint_set command that sets a breakpoint.`
	`548`	`+ * @param {object} breakpoint`
	`549`	`+ * @param {string} breakpoint.type - the type of breakpoint. Can be 'line' or 'exception'`
	`550`	`+ * @param {string} [breakpoint.fileUri] - the file URI to break on if type is 'line'`
	`551`	`+ * @param {number} [breakpoint.line] - the line to break on if type is 'line'`
	`552`	`+ * @param {string} [breakpoint.exception] - the exception class name to break on if type is 'exception'`
	`553`	`+ * @returns Promise.<BreakpointSetResponse>`
`542`	`554`	`*/`
`543`		`- public sendBreakpointSetCommand(breakpoint: {type: string, file?: string, line?: number, exception?: string}): Promise<BreakpointSetResponse> {`
	`555`	`+ public sendBreakpointSetCommand(breakpoint: {type: string, fileUri?: string, line?: number, exception?: string}): Promise<BreakpointSetResponse> {`
`544`	`556`	let args = `-t ${breakpoint.type} `;
`545`	`557`	`if (breakpoint.type === 'line') {`
`546`		- args += `-f ${breakpoint.file} -n ${breakpoint.line}`;
	`558`	+ args += `-f ${breakpoint.fileUri} -n ${breakpoint.line}`;
`547`	`559`	`} else if (breakpoint.type === 'exception') {`
`548`	`560`	args += `-x ${breakpoint.exception}`;
`549`	`561`	`} else {`
`@@ -552,39 +564,46 @@ export class Connection extends DbgpConnection {`
`552`	`564`	`return this._enqueueCommand('breakpoint_set', args).then(document => new BreakpointSetResponse(document, this));`
`553`	`565`	`}`
`554`	`566`
	`567`	`+ /** sends a breakpoint_list command */`
`555`	`568`	`public sendBreakpointListCommand(): Promise<BreakpointListResponse> {`
`556`	`569`	`return this._enqueueCommand('breakpoint_list').then(document => new BreakpointListResponse(document, this));`
`557`	`570`	`}`
`558`	`571`
	`572`	`+ /** sends a breakpoint_remove command */`
`559`	`573`	`public sendBreakpointRemoveCommand(breakpoint: Breakpoint): Promise<Response> {`
`560`	`574`	return this._enqueueCommand('breakpoint_remove', `-d ${breakpoint.id}`).then(document => new Response(document, this));
`561`	`575`	`}`
`562`	`576`
`563`	`577`	`// ----------------------------- continuation ---------------------------------`
`564`	`578`
	`579`	`+ /** sends a run command */`
`565`	`580`	`public sendRunCommand(): Promise<StatusResponse> {`
`566`	`581`	`return this._enqueueCommand('run').then(document => new StatusResponse(document, this));`
`567`	`582`	`}`
`568`	`583`
	`584`	`+ /** sends a step_into command */`
`569`	`585`	`public sendStepIntoCommand(): Promise<StatusResponse> {`
`570`	`586`	`return this._enqueueCommand('step_into').then(document => new StatusResponse(document, this));`
`571`	`587`	`}`
`572`	`588`
	`589`	`+ /** sends a step_over command */`
`573`	`590`	`public sendStepOverCommand(): Promise<StatusResponse> {`
`574`	`591`	`return this._enqueueCommand('step_over').then(document => new StatusResponse(document, this));`
`575`	`592`	`}`
`576`	`593`
	`594`	`+ /** sends a step_out command */`
`577`	`595`	`public sendStepOutCommand(): Promise<StatusResponse> {`
`578`	`596`	`return this._enqueueCommand('step_out').then(document => new StatusResponse(document, this));`
`579`	`597`	`}`
`580`	`598`
	`599`	`+ /** sends a stop command */`
`581`	`600`	`public sendStopCommand(): Promise<StatusResponse> {`
`582`	`601`	`return this._enqueueCommand('stop').then(document => new StatusResponse(document, this));`
`583`	`602`	`}`
`584`	`603`
`585`	`604`	`// ------------------------------ stack ----------------------------------------`
`586`	`605`
`587`		`- /** Sends a stack_get request */`
	`606`	`+ /** Sends a stack_get command */`
`588`	`607`	`public sendStackGetCommand(): Promise<StackGetResponse> {`
`589`	`608`	`return this._enqueueCommand('stack_get').then(document => new StackGetResponse(document, this));`
`590`	`609`	`}`
`@@ -608,6 +627,7 @@ export class Connection extends DbgpConnection {`
`608`	`627`
`609`	`628`	`// ------------------------------- eval -----------------------------------------`
`610`	`629`
	`630`	`+ /** sends an eval command */`
`611`	`631`	`public sendEvalCommand(expression: string): Promise<EvalResponse> {`
`612`	`632`	`return this._enqueueCommand('eval', null, expression).then(document => new EvalResponse(document, this));`
`613`	`633`	`}`