deprecated: a use of a function its author has deprecated

A function marked @[deprecated("...")] still works. Every use of it from outside the module that declares it gets this warning, which carries the author’s message: usually the name of the replacement. A warning does not change the exit status, so the program still compiles and runs.

A program that triggers it

mod Main do
  mod Temperature do
    @[deprecated("use `Temperature.to_fahrenheit` instead")]
    fn c_to_f(c : Int) : Int do
      to_fahrenheit(c)
    end

    fn to_fahrenheit(c : Int) : Int do
      c * 9 / 5 + 32
    end
  end

  fn main() : Int do
    Temperature.c_to_f(100)
  end
end

The fix

Do what the message says. Here that is calling the replacement:

mod Main do
  mod Temperature do
    @[deprecated("use `Temperature.to_fahrenheit` instead")]
    fn c_to_f(c : Int) : Int do
      to_fahrenheit(c)
    end

    fn to_fahrenheit(c : Int) : Int do
      c * 9 / 5 + 32
    end
  end

  fn main() : Int do
    Temperature.to_fahrenheit(100)
  end
end

What counts as a use

Any reference to the function from outside its module: a call, a pipe into it, passing it as a value, and a call through a name brought in with use or alias. Each use gets its own warning, at the use.

A use inside the declaring module, or inside a module nested in it, does not warn. The module that deprecates a function usually still has to call it, and the old name is often implemented in terms of the new one or the other way round.

Marking a function deprecated

The attribute takes one string, the message, and goes directly above the fn or pfn (after a doc string, if there is one):

mod Temperature do
  doc "Converts Celsius to Fahrenheit."
  @[deprecated("use `Temperature.to_fahrenheit` instead")]
  fn c_to_f(c : Int) : Int do
    to_fahrenheit(c)
  end

  fn to_fahrenheit(c : Int) : Int do
    c * 9 / 5 + 32
  end
end

The message is required. Write what the caller should do instead, since it is the whole text of the warning they see. @[deprecated] marks functions only; on a type or a mod it is a parse error.

Why the rule exists

Removing a function breaks every caller at once. Deprecating it first gives them a release in which their code still builds and the compiler tells them what to change. The compatibility policy says how long a deprecated function stays before it can be removed.

See also: the compatibility policy.