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
) = @_;
[download]

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) = @_;
}
[download]

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
[download]

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.