Request for Comments: More annotations for Perl plugin for IntelliJ

[hurricup]

This is a real request for comments and suggestions. If you are using Perl plugin for IntelliJ, you could see that it uses annotations to help working with project and resolve methods, like #@deprecated, #@returns and #@method

Currently I'd like to add two more annotations and thinking about the proper format.

Variable Types

Currently, variable type may be guessed by the plugin by explicit type definition, like my Foo::Bar $var; or by return value, like my $var = Foo::Bar->new();

Perl explicit type has a flaw: you can't specify different types on multiple declarations, only one for all of them, like my Foo::Bar ($var1, $var2, $var3);, what is not really convenient for arguments unpacking, so you need to change compact format to larger and slower multiple shifts.

So the idea here is to introduce #@type annotation and unpacking will look like:

my (
    $self, 
    #@type Foo::Bar
    $foobar,
    #@type Foo::Baz
    $foobaz
) = @_;

For arrayrefs and hashrefs i'd like to use Moose format from isa parameter of has statement: HashRef[Foo::Bar] and ArrayRef[Foo::Bar].

Subs arguments

To improve subs signatures on auto-completion and auto-completion itself, I'd like to add #@args annotation, which may provide additional information about sub argument, like type, optionality and named arguments. Example:

#@returns Some::Class
#@arg $arg1 Foo::Bar    # some description
#@arg $arg2 Foo::Baz    
#@arg $arg3             # just a description
#@arg %args key1, key2 Foo::Zoo, key3 
sub somesub{
    my ($self, $arg1, $arg2, $arg3, %args) = @_;
}

This idea is pretty new, so I don't really know what is the best way to do this. Typing format is pretty obvious but other features - not.

Optional vs mandatory:

#@arg [$var1 HashRef[Foo::Bar]] # description
or
#@arg optional $var1 HashRef[Foo::Bar] # description
or 
#@oarg $var1 HashRef[Foo::Bar] # description

Named parameters looks pretty solid, aside it's not possible to add a description, but not sure how to use it yet anyway.

I'm also going to make possible to move all subs annotations to a separate file, like Python stub file, it's necessary to work with external OOP modules, which are not annotated and won't ever be.

Please, share your ideas and suggestions.

[Corion]

For subroutine signatures, why not simply have people use subroutine signatures as god intended? The effort of adding the custom signatures as comments seems to be about equal to adding the signatures directly...

[hurricup]

Well, because at least

WARNING: Subroutine signatures are experimental. The feature may be modified or removed in future versions of Perl.

And it's not good practice to use experimental features in production code. And if I remember right, in one of the latest versions signatures syntax been changed (position). And default signatures does not supports typing. And I can't force other authors to use them, so can't have completion/navigation on their modules.

[Athanasius]

Hello hurricup,

Well, if you don’t like Signatures, has a number of other options you should at least consider:

• signatures
• Method::Signatures
• Function::Parameters
• Attribute::Signature
• Perl6::Signature (but this is an alpha release)
• Perl6::Parameters

Hope that helps,

[Anonymous Monk]

:)

comments or experimental feature,

comments or experimental code,

comments or code

comments or code

comments or code

Hmm, comments just aren't code

Is anyone (even you ) using this annotations feature? More than to simply try/test it out? That you've gotten at least one feature request about it?

Keeping the stuff in a separate file sounds good :D