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
_______________________________________________
swift-evolution mailing list
swift-evolution@swift.org
https://lists.swift.org/mailman/listinfo/swift-evolution
