Proposal updates

Author: simonjbeaumont

Sources/swift-openapi-generator/Documentation.docc/Proposals/SOAR-0013.md

@@ -29,13 +29,11 @@ Introduce a new naming strategy as an opt-in feature, instructing the generator
 
 The purpose of Swift OpenAPI Generator is to generate Swift code from OpenAPI documents. As part of that process, names specified in the OpenAPI document have to be converted to names in Swift code - and there are many ways to do that. We call these "naming strategies" in this proposal.
 
-When Swift OpenAPI Generator 0.1.0 went open-source in May 2023, it had a simple naming strategy that produced relatively conventional Swift identifiers from OpenAPI names. However, when tested on a large test corpus of around 3000 OpenAPI documents, it produced an unacceptably high number of non-compiling packages due to naming conflicts.
+When Swift OpenAPI Generator 0.1.0 went open-source in May 2023, it had a simple naming strategy that produced relatively conventional Swift identifiers from OpenAPI names.
 
-The root cause of conflicts are the different allowed character sets for OpenAPI names and Swift identifiers. OpenAPI has a more flexible allowed character set than Swift identifiers.
+However, when tested on a large test corpus of around 3000 OpenAPI documents, it produced an unacceptably high number of non-compiling packages due to naming conflicts. The root cause of conflicts are the different allowed character sets for OpenAPI names and Swift identifiers. OpenAPI has a more flexible allowed character set than Swift identifiers.
 
-The existing naming strategy also avoids changing the character casing, as we discovered OpenAPI documents with properties within an object schema that only differred by case.
-
-In response to the findings on the test corpus, the proposal [SOAR-0001: Improved mapping of identifiers][soar0001], which shipped in 0.2.0, changed the naming strategy to avoid conflicts and resulted in no conflicts produced in the test corpus, allowing hundreds of additional OpenAPI documents to be correctly handled by Swift OpenAPI Generator.
+In response to these findings, [SOAR-0001: Improved mapping of identifiers][soar0001], which shipped in 0.2.0, changed the naming strategy to avoid these conflicts, allowing hundreds of additional OpenAPI documents to be correctly handled by Swift OpenAPI Generator. This addressed all issues related to naming conflicts in the test corpus. This is the existing naming strategy today. This strategy also avoids changing the character casing, as we discovered OpenAPI documents with properties within an object schema that only differed by case.
 
 The way the conflicts are avoided in the naming strategy from SOAR-0001 is by turning any special characters (any characters that aren't letters, numbers, or an underscore) into words, resulting in identifiers like:
 
@@ -46,9 +44,7 @@ user-name -> user_hyphen_name
 my.org.User -> my_period_org_period_User
 ```
 
-The decision to rely on a naming strategy that can handle all the tested OpenAPI documents was the right one, and it has allowed more developers to get value from Swift OpenAPI Generator since then.
-
-However, we've also [heard][issue1] [from][issue2] [adopters][issue3] [who][issue4] don't use special characters in their OpenAPI documents, and how some of the generated Swift names are still difficult to read and are simply unpleasant to look at.
+Our priority was to support as many valid OpenAPI documents as possible. However, we've also [heard][issue1] [from][issue2] [adopters][issue3] [who][issue4] would prefer more idiomatic generated code and don't benefit from the defensive naming strategy.
 
 ### Proposed solution
 
@@ -58,10 +54,12 @@ For clarity, we'll refer to the existing naming strategy as the "defensive" nami
 
 Part of the new strategy is adjusting the capitalization, and producing `UpperCamelCase` names for types, and `lowerCamelCase` names for members, as is common in hand-written Swift code.
 
-> Warning: Due to the idiomatic naming strategy changing capitalization, it is possible to get non-compiling Swift code from more OpenAPI documents than with the defensive naming strategy. We recommend you try to use the idiomatic naming strategy on your OpenAPI document, and if it produces conflicts, switch back to the defensive naming strategy, which avoids conflicts. However, the number of documents that result in conflicts with the idiomatic naming strategy is estimated to be very small (<1%).
+After attempting to produce an more idiomatic identifier, this strategy will fall back to the defensive strategy, to replace any remaining invalid symbols.
 
 The second feature introduced as part of this proposal is a way to provide a string -> string map to fully override only specific OpenAPI names and provide their exact Swift identifiers. This is the ultimate escape hatch when both naming strategies fail to provide the desired result for the adopter.
 
+> Note: Because the idiomatic naming strategy can change capitalization, in rare cases it can still generate non-compiling code from a valid OpenAPI document. We recommend using the idiomatic naming strategy and, if it produces conflicts, address them using name overrides, or switch back to the defensive naming strategy.
+
 #### Examples
 
 To get a sense for the proposed change, check out the table below that compares the existing defensive strategy against the proposed idiomatic strategy on a set of examples:
@@ -101,7 +99,7 @@ The idiomatic naming strategy (check out the current code [here][impl], look for
 
 > Note: We let [`Swift.String.isLetter`](https://developer.apple.com/documentation/swift/character/isletter) decide whether a character is a letter, which has the advantage of including letters in the non-ASCII range. Swift identifiers also support a [wide range](https://docs.swift.org/swift-book/documentation/the-swift-programming-language/lexicalstructure/#Identifiers) of alphanumeric characters.
 
-If the OpenAPI name includes any _other_ characters, the idiomatic naming strategy _falls back_ to the defensive naming strategy for that input string only. 
+If the OpenAPI name includes any _other_ characters, the idiomatic naming strategy _falls back_ to the defensive naming strategy for that input string only.
 
 There's a second special case for handling all uppercased names, such as `NOT_AVAILABLE` - if this situation is detected, the idiomatic naming strategy turns it into `NotAvailable` for types and `notAvailable` for members.