Docs: for rjust and ljust, provide comment on what to use instead?

[jessitron]

Back in Elixir 1.2, String.rjust and String.ljust add padding to strings. They show in the REPL, but then when I looked for docs on them, there weren't any.

I see that these are deprecated -- Google led me to the source code when I couldn't find them in the documentation.
Please in those comments can we say which functions to use instead?

The 1.2 API is significant because the PragProg book will not update past Elixir 1.2; to get Elixir 1.3 or later I have to pay another $25. So, my 1.2 copy was fully updated but led me astray, and then I struggled to find what to do instead.

pad_leading and pad_trailing are much better names, agree. It would have helped to see those names in the comments deprecating rjust.

[eksperimental]

Thank you for the report @jessitron
This is definitely a bug in the documentation,
We should update the Deprecations page, as well as the CHANGELOG files for Elixir version it was soft-deprecated.

There are more String functions that have not been documented.
Check elixir_dispatch.erl for a list of functions:
https://github.com/elixir-lang/elixir/blob/170019c/lib/elixir/src/elixir_dispatch.erl#L365-L415

[josevalim]

Thanks for the report @jessitron!

In earlier versions, when a function was deprecated, we did remove it from the documentation. Others start to report the same issue as you did above and we changed the deprecation strategy to keep the old docs around but introduce warnings.

@eksperimental also added a Deprecations page that will be part of Elixir v1.5. Although that page is currently missing the String ones. We will be sure to make it up to date. And if you try to call any of those functions in Elixir v1.5, you will also get a warning pointing towards the proper implementation.

And for those really stuck with old versions, you can consult the docs from the old stable branches: http://elixir-lang.org/docs.html

TL;DR - we have already learned our lesson and changed our deprecation strategy to make it less confusing. :)