From f570be1d91e698647d0e0ef39eb3071b4c2a874e Mon Sep 17 00:00:00 2001
From: Johannes Rieken <johannes.rieken@gmail.com>
Date: Thu, 11 Jun 2020 09:57:01 +0200
Subject: [PATCH] more jsdoc for `extUriIgnorePathCase` and
 `extUriBiasedIgnorePathCase`,
 https://github.com/microsoft/vscode/issues/93368

---
 src/vs/base/common/resources.ts | 33 +++++++++++++++++++++++++--------
 1 file changed, 25 insertions(+), 8 deletions(-)

diff --git a/src/vs/base/common/resources.ts b/src/vs/base/common/resources.ts
index 20c1cbafe88..902076cc1cb 100644
--- a/src/vs/base/common/resources.ts
+++ b/src/vs/base/common/resources.ts
@@ -313,11 +313,6 @@ export class ExtUri implements IExtUri {
 	}
 }
 
-export const extUriBiasedIgnorePathCase = new ExtUri(uri => {
-	// A file scheme resource is in the same platform as code, so ignore case for non linux platforms
-	// Resource can be from another platform. Lowering the case as an hack. Should come from File system provider
-	return uri.scheme === Schemas.file ? !isLinux : true;
-});
 
 /**
  * Unbiased utility that takes uris "as they are". This means it can be interchanged with
@@ -329,11 +324,33 @@ export const extUriBiasedIgnorePathCase = new ExtUri(uri => {
 export const extUri = new ExtUri(() => false);
 
 /**
- * BIASED utility that always ignores the casing of uris path. ONLY use these util if you
+ * BIASED utility that _mostly_ ignored the case of urs paths. ONLY use this util if you
  * understand what you are doing.
  *
- * Note that `IUriIdentityService#extUri` is a better replacement for this because that utility
- * knows when path casing matters and when not.
+ * This utility is INCOMPATIBLE with `uri.toString()`-usages and both CANNOT be used interchanged.
+ *
+ * When dealing with uris from files or documents, `extUri` (the unbiased friend)is sufficient
+ * because those uris come from a "trustworthy source". When creating unknown uris it's always
+ * better to use `IUriIdentityService` which exposes an `IExtUri`-instance which knows when path
+ * casing matters.
+ */
+export const extUriBiasedIgnorePathCase = new ExtUri(uri => {
+	// A file scheme resource is in the same platform as code, so ignore case for non linux platforms
+	// Resource can be from another platform. Lowering the case as an hack. Should come from File system provider
+	return uri.scheme === Schemas.file ? !isLinux : true;
+});
+
+
+/**
+ * BIASED utility that always ignores the casing of uris paths. ONLY use this util if you
+ * understand what you are doing.
+ *
+ * This utility is INCOMPATIBLE with `uri.toString()`-usages and both CANNOT be used interchanged.
+ *
+ * When dealing with uris from files or documents, `extUri` (the unbiased friend)is sufficient
+ * because those uris come from a "trustworthy source". When creating unknown uris it's always
+ * better to use `IUriIdentityService` which exposes an `IExtUri`-instance which knows when path
+ * casing matters.
  */
 export const extUriIgnorePathCase = new ExtUri(_ => true);