swift: Add documentation to reserved keywords

apollographql · Sep 10, 2019 · 54c384b · 54c384b
1 parent 87d5b4a
commit 54c384b
Showing 1 changed file with 36 additions and 9 deletions.
diff --git a/packages/apollo-codegen-swift/src/language.ts b/packages/apollo-codegen-swift/src/language.ts
@@ -31,18 +31,45 @@ export interface Property {
   description?: string;
 }
 
+/**
+ * Swift identifiers that are keywords
+ *
+ * Some of these are context-dependent and can be used as identifiers outside of the relevant
+ * context. As we don't understand context, we will treat them as keywords in all contexts.
+ *
+ * This list does not include keywords that aren't identifiers, such as `#available`.
+ */
 // prettier-ignore
-const reservedKeywords = new Set(['associatedtype', 'class', 'deinit', 'enum', 'extension',
-  'fileprivate', 'func', 'import', 'init', 'inout', 'internal', 'let', 'open',
-  'operator', 'private', 'protocol', 'public', 'static', 'struct', 'subscript',
-  'typealias', 'var', 'break', 'case', 'continue', 'default', 'defer', 'do',
-  'else', 'fallthrough', 'for', 'guard', 'if', 'in', 'repeat', 'return',
-  'switch', 'where', 'while', 'as', 'Any', 'catch', 'false', 'is', 'nil',
-  'rethrows', 'super', 'self', 'Self', 'throw', 'throws', 'true', 'try',
+const reservedKeywords = new Set([
+  // https://docs.swift.org/swift-book/ReferenceManual/LexicalStructure.html#ID413
+  // Keywords used in declarations
+  'associatedtype', 'class', 'deinit', 'enum', 'extension', 'fileprivate',
+  'func', 'import', 'init', 'inout', 'internal', 'let', 'open', 'operator',
+  'private', 'protocol', 'public', 'static', 'struct', 'subscript',
+  'typealias', 'var',
+  // Keywords used in statements
+  'break', 'case', 'continue', 'default', 'defer', 'do', 'else', 'fallthrough',
+  'for', 'guard', 'if', 'in', 'repeat', 'return', 'switch', 'where', 'while',
+  // Keywords used in expressions and types
+  'as', 'Any', 'catch', 'false', 'is', 'nil', 'rethrows', 'super', 'self',
+  'Self', 'throw', 'throws', 'true', 'try',
+  // Keywords used in patterns
+  '_',
+  // Keywords reserved in particular contexts
   'associativity', 'convenience', 'dynamic', 'didSet', 'final', 'get', 'infix',
   'indirect', 'lazy', 'left', 'mutating', 'none', 'nonmutating', 'optional',
-  'override', 'postfix', 'precedence', 'prefix', 'Protocol', 'required', 'right',
-  'set', 'Type', 'unowned', 'weak', 'willSet']);
+  'override', 'postfix', 'precedence', 'prefix', 'Protocol', 'required',
+  'right', 'set', 'Type', 'unowned', 'weak', 'willSet'
+]);
+/**
+ * Swift identifiers that are keywords in member position
+ *
+ * This is the subset of keywords that are known to still be keywords in member position. The
+ * documentation is not explicit about which keywords qualify, but these are the ones that are
+ * known to have meaning in member position.
+ *
+ * We use this to avoid unnecessary escaping with expressions like `.public`.
+ */
 const reservedMemberKeywords = new Set(["self", "Type", "Protocol"]);
 
 /**