Clarify that #file is preferred over #fileID in the Swift 6 language mode

This PR updates the API design guidelines to clarify that #file should be preferred over #fileID in the Swift 6 language mode. Started a discussion here on the Swift Evolution forums.

Motivation:

#fileID was introduced by SE-0285 to ease the transition where #file changed from aliasing #filePath in Swift 5 mode to aliasing #fileID in Swift 6 mode.

The proposal mentions several times that #file is the long-term preferred API, and that #fileID should eventually be deprecated:

#file will continue to produce the same string as #filePath in the Swift 5 and earlier language modes. When code is compiled using [Swift 6 mode], #file will generate the same string as #fileID, and #fileID will be deprecated.

#fileID is intended to allow Swift 5.3 code to adopt the new, more compact literals before the behavior of #file changes. In language version modes where #file produces the same string as #fileID, #fileID will be deprecated.

Modifications:

This PR adds the following additional advice to the section discussing #fileID:

Prefer #file in the Swift 6 language mode or later, where it has the same behavior as #fileID

Result:

Now it will be more clear that #file is recommended over #fileID in Swift 6 mode.

Eventually it will make sense to reframe this entire section around "prefer #file over #filePath". For now while the Swift 5 and Swift 6 modes broadly coexist, I think the anchoring the discussion around #fileID still makes the most sense.

swiftlang / swift-org-website