Add doc comment for deprecation when disabling deprecation warnings

[jimisaacs]

Use case

Currently we need to use warningsOnDeprecatedUsage: .exclude so we may keep SWIFT_TREAT_WARNINGS_AS_ERRORS enabled in our app, because it's a rather unreasonable ask to have someone drop everything to fix GQL deprecations when codegen picks them up. It's different than the reason we have this setting on which is to manage warnings when moving from SDK version to SDK version. We are more in control of that timing, and not so much on when a field is deprected somewhere in a federated graph.

Describe the solution you'd like

Currently it's great to have the facility of disabling swift deprecation warnings via warningsOnDeprecatedUsage: .exclude, but instead of outputting nothing, it would be nice to have a doc comment, something like /// GraphQL deprecated: message when annotations are disabled. This would still allow a text search from within Xcode.

[ethankao]

Could we explore to use swift comment doc?

I also think using deprecated annotation for experimental fields is very strange. We don't want to prevent ppl from using it.

There are a few extensions we can considered to use to support deprecation and experimental.

https://github.com/apple/swift/blob/main/docs/DocumentationComments.md

/// - Experiment: Experimental field message /// - Warning: Deprecated field message.

[ethankao]

Ignore my experimental comment. I just learned that it's an internal annotation we have implemented.

[calvincestari]

I do like the suggestion of putting the deprecation 'notice' into a comment vs. annotation so there is always some indication of it being deprecated. My conflicting feeling about it is workflow-specific and the deprecation being in a comment is not likely to promote change.