Deprecating a Function

deprecated "use refund_order instead" fix refund_order(order)
pub fn refund(order: Order) -> Receipt ! RefundError uses Payments { … }

• deprecated goes on its own line before the function: after its doc comment, before pub.
• The text in quotes says what to use instead. Every call shows it as a warning.
• fix, which may be left out, is what each call becomes. The function's parameters in it stand for each call's arguments.

From warning to rewrite

half is replaced by half_of. The old function stays, so no caller breaks on the day it changes:

/// Half of `n`, rounded down.
pub fn half_of(n: Int) -> Int {
    n.div_floor(2)
}

/// The old name, kept so callers have time to move.
deprecated "use half_of instead" fix half_of(n)
pub fn half(n: Int) -> Int {
    half_of(n)
}

use billing
use billing.{half}

fn main() {
    print(billing.half(4))
    print(half(6))
}

2
3
warning: `half` is deprecated: use half_of instead (spec 12.6)
 --> src/main.kav:5:11
  |
5 |     print(billing.half(4))
  |           ^^^^^^^^^^^^

warning: `half` is deprecated: use half_of instead (spec 12.6)
 --> src/main.kav:6:11
  |
6 |     print(half(6))
  |           ^^^^

src/main.kav: Replace with `billing.half_of(4)`

2
3
warning: `half` is deprecated: use half_of instead (spec 12.6)
 --> src/main.kav:6:11
  |
6 |     print(half(6))
  |           ^^^^

• Both calls warn, each with the message from deprecated.
• billing.half(4) becomes billing.half_of(4): a call made through its module keeps the module.
• half(6) stays as it is, with its warning. It was brought in with use billing.{half}, so half_of isn't known there, and the rewrite wouldn't compile. kavach fix never makes an edit that adds an error. Add half_of to the use, and the next kavach fix rewrites it.
• The editor offers the same rewrite as a quick fix, one call at a time.

Arguments keep their meaning

Where the fix uses a parameter inside an operator, an argument that is more than a name, a literal, a field or a call goes in parentheses. With fix half_of(n * 2), half(a + b) becomes half_of((a + b) * 2), never half_of(a + b * 2). A parameter the call leaves out stands for its default.

Only before a function

Today only functions can be deprecated. Anywhere else, deprecated is an error:

deprecated "use Order instead"
type OldOrder {
    id: Int
}

fn main() {
    print("never runs")
}

error: `deprecated` only goes before a function (spec 12.6)

A fix is code like any other, so a name in it that doesn't exist is the usual error, with a suggestion. Methods, types and fields can't be deprecated yet: that is an open question in spec 12.

The other fixes kavach fix makes are on its own page.