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.

In reply to Request for Comments: More annotations for Perl plugin for IntelliJ by hurricup

Title:
Use:  <p> text here (a paragraph) </p>
and:  <code> code here </code>
to format your post, it's "PerlMonks-approved HTML":


  • Posts are HTML formatted. Put <p> </p> tags around your paragraphs. Put <code> </code> tags around your code and data!
  • Titles consisting of a single word are discouraged, and in most cases are disallowed outright.
  • Read Where should I post X? if you're not absolutely sure you're posting in the right place.
  • Please read these before you post! —
  • Posts may use any of the Perl Monks Approved HTML tags:
    a, abbr, b, big, blockquote, br, caption, center, col, colgroup, dd, del, details, div, dl, dt, em, font, h1, h2, h3, h4, h5, h6, hr, i, ins, li, ol, p, pre, readmore, small, span, spoiler, strike, strong, sub, summary, sup, table, tbody, td, tfoot, th, thead, tr, tt, u, ul, wbr
  • You may need to use entities for some characters, as follows. (Exception: Within code tags, you can put the characters literally.)
            For:     Use:
    & &amp;
    < &lt;
    > &gt;
    [ &#91;
    ] &#93;
  • Link using PerlMonks shortcuts! What shortcuts can I use for linking?
  • See Writeup Formatting Tips and other pages linked from there for more info.