[swift-evolution] [Discussion] Deprecation Linking

[Paul Ossenbruggen]

I work on an API and like any API, we frequently deprecate methods (more than we would like). I think would be useful, when you deprecate something there is a link from the old method to the new method(s). With this facility it would be possible to match the old parameter name with the new names, assuming they match in type and name and automatically fill in much of the information so you don’t have to do as much work to adopt the new API. The user would just have to add the new parameters, if a parameter is removed, it would delete it. There would also be some basic checking done to make sure the new API matched. This would work on the vast bulk of APIs. When there are multiple choices, multiple replacements would be shown and selected in the IDE. It would use most of the current attributes available in Swift. I am thinking of syntax something like this, very rough: 

#begindeprecation(message=“optional comment”, available=iOS 8.0)
func fetchProjects(query query : String?) {
   // some code
}
#replacement(message=“some comment”), available=iOS 9.0)
func fetchProjects(query query : String?, scope : String?) {
   // some code
}
#replacement(message=“some comment 2”, available=iOS 9.0) 
func fetchProjects((query query : String?, scope : NSPredicate) {
}
#enddeprecation

In this example, the IDE would show the two replacements, and let you select one of them, then it would automatically fill in the “query" with the replacement, and then leave a place for you to enter the “scope” parameter. If it is just deprecated with no replacements you would just leave out the #replacement part. The comment part is optional. The comments would also appear in the documentation for the method as it currently does with the deprecation attributes. Eventually when you are done supporting the deprecation, you would remove the # and the old methods. 

The idea is to enhance the process of deprecation, as well as simplify and speed adoption of the new APIs. The user would not have to spend as much time researching the new way to do things, they would just be presented with the new way. I imagine this would also be useful to developers on the same team. I speak specifically of methods here but this would apply to other entities that you might want to deprecate as well. I am sure there is more to consider here but thought I would start out simple and the most common case. 

- Paul 






-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.swift.org/pipermail/swift-evolution/attachments/20160407/92761521/attachment.html>