extending the documentation of DEPRECATED

[MARTIMM]

The problem

Missing information about DEPRECATED as a routine. I file this issue as suggested by JJ Merelo in the e-mail discussion 'DEPRECATED routine' on the perl6-users@perl.org list.

My first mail which started the discussion;

Studying GTK::Simple I found about the existence of a routine DEPRECATED which I couldn't find in the Perl6 documents. Reading from the code I see that it needs 3 arguments, start version of deprecation, version when it will be removed and a string like the one in 'is DEPRECATED()' trait.

A example like

sub gtk_builder_add_from_file ( ... ) {
  DEPRECATED(
    'other multi version of gtk_builder_add_from_file', '0.17.10', '0.20.0'
  );
  ...
}

Gives a result like;

Saw 1 occurrence of deprecated code.
================================================================================
Sub gtk_builder_add_from_file (from Gnome::Gtk3::Builder) seen at:
/home/marcel/Languages/Perl6/Projects/perl6-gnome-gtk3/../perl6-gnome-native/lib/Gnome/N/X.pm6 (Gnome::N::X), line 109
Deprecated since v0.17.10, will be removed with release v0.20.0!
Please use other version of gtk_builder_add_from_file instead.

Brad Gilbert said;

The `DEPRECATED` function is a feature of Rakudo, not Perl6.
Which means that how it works, and even its existence could be changed without warning.

It was added so that the compiler and runtime can mark features of itself as deprecated.
Because of the design of the compiler and runtime, it leaks out into the userspace.
It is not in ROAST so it is not Perl6.
`is DEPRECATED` is https://github.com/perl6/roast/blob/master/S02-types/isDEPRECATED.t

    my $a;
    my $awith;
    sub a     is DEPRECATED              { $a++     };
    sub awith is DEPRECATED("'fnorkle'") { $awith++ };

The only thing this use of `DEPRECATED` shows, is that `is DEPRECATED` could use a new
feature for indicating versions.

Suggestions

Update according to JJ Merelo;

Still, it's better to mention it in the documentation with all possible caveats.
I'd appreciate if you opened an issue, linking this question.

[lizmat]

FWIW, I consider the &DEPRECATED sub as an implementation detail that can be moved as soon as someone has the time to move it. I would therefore consider it a bad idea to document it. If the documentation of the is DEPRECATED trait is insufficient, then that should be improved!

[JJ]

@lizmat we should probably do both. An undocumented feature is simply an undocumented feature, and only causes confusion and questions in the mailing list. An implementation detail can be documented as such, with all necessary caveats. After all, there's nothing more apt to be deprecated than DEPRECATED.

[coke]

We should not, in general, be documenting implementation details in the language spec site.

I think the best place for this would be someplace like https://github.com/rakudo/rakudo/wiki/Implementation+Details.

We could definitely add a one liner link under 'is DEPRECATED' to that wiki if it existed, but that's it.