document debug URI format

src/vs/workbench/parts/debug/browser/debugContentProvider.ts

@@ -14,6 +14,19 @@ import { ITextModelService, ITextModelContentProvider } from 'vs/editor/common/s
 import { IWorkbenchContribution } from 'vs/workbench/common/contributions';
 import { DEBUG_SCHEME, IDebugService, IProcess } from 'vs/workbench/parts/debug/common/debug';
 
+/**
+ * Debug URI format
+ *
+ * a debug URI represents a Source object and the debug session where the Source comes from.
+ *
+ *       debug:arbitrary_path?session=123e4567-e89b-12d3-a456-426655440000&ref=1016
+ *       \___/ \____________/ \__________________________________________/ \______/
+ *         |          |                             |                          |
+ *      scheme   source.path                    session id            source.referencequery
+ *
+ * the arbitrary_path and the session id are encoded with 'encodeURIComponent'
+ *
+ */
 export class DebugContentProvider implements IWorkbenchContribution, ITextModelContentProvider {
 
 	constructor(