Annotations for Perl

hurricup has asked for the wisdom of the Perl Monks concerning the following question:

Hello Perl coders!

Got a problem and possible solution, need a feedback from community.

As you may know, I'm currently working on Perl5 plugin for Intellij IDEA, and work is going fine, it works and can do a lot of useful things. But i've encountered a problem.

In order to link sub usage and it's definition or declaration, i need to know, in which namespace to look. And it's not a problem when you are using obvious calls:

somesub(); # just looking current namespace
Foo::Bar::somesub(); # obviously, looking in Foo::Bar

# and now you can even do this:

my Foo::Bar $object;

$object->somesub(); # will understand that it's a Foo::Bar's sub
[download]

But, what to do when it's used like:

Foo::Bar->new()->some_geter()->somethingelse();
[download]

Of course, it's possible to constantly work on smart algorythms, which will be able to analyse previous sub in "dereference" chain and try to guess, what was returned.

But it's an endless work as a Perl itself and resourse-consuming.

I belive that the best way here is to introduce a Java-like annotations:

#@Returns Foo::Bar
sub somefunc{
...
}
[download]

Here, IDE parser can easily find out, that somefunc returns Foo::Bar object. And from the Perl's perspective, it's still just a comment.

Currently thinking about following annotations:

#@override - marks that method overrides something from one of the parents
#@deprecated - marks that method is deprecated
#@returns Package::Name - marks that method returns an object of Package::Name
#@returns [Package::Name] - array of objects
#@returns {Package::Name} - hash with objects as values

There are lot of useful IDE hints could be, like #@defined, #@undefinable and so on, but these above i really need.

I thought about using attributes, but not sure it's such good idea, and, btw, it would be easy to convert such form of annotations to another one if Perl devs introduce something useful for this.

Really need a feedback and ideas.

Comment on Annotations for Perl Select or Download Code

Replies are listed 'Best First'.
Re: Annotations for Perl by choroba (Cardinal) on Jun 02, 2015 at 16:59 UTC
In Perl, a subroutine/method can return various things, depending on context, but also the arguments, global state, local time, etc. I'm not saying it's a good habit, but an IDE should help you program, not restrict you. Perl programmers don't write Java in Perl, the thinking is different, and with enough experience, it leads to organised code, too, but organised in a different way. Being dynamic isn't Perl's weakness, but strength, when used properly. لսႽ† ᥲᥒ⚪⟊Ⴙᘓᖇ Ꮅᘓᖇ⎱ Ⴙᥲ𝇋ƙᘓᖇ	[reply]
Re^2: Annotations for Perl by hurricup (Pilgrim) on Jun 02, 2015 at 17:19 UTC
Yes, i know that. But there is a big difference between writing one-string and production OOP code. For first- you don't need IDE My purpose is to make tool for people developing readable structural projects, not for perl magicians :) And after all, do you have an alternative solution for described problem?	[reply]
Re^3: Annotations for Perl by Anonymous Monk on Jun 02, 2015 at 22:53 UTC
Yes, i know that. But there is a big difference between writing one-string and production OOP code. choroba is talking about "production", he is not talking about "one-string" My purpose is to make tool for people developing readable structural projects, not for perl magicians :) Why would those people start with a code editor, instead of some UML code generating tool? And after all, do you have an alternative solution for described problem? Module::Info, Doxygen::Filter::Perl,.... :)	[reply]
Re^4: Annotations for Perl by hurricup (Pilgrim) on Jun 03, 2015 at 05:42 UTC
Re: Annotations for Perl by RonW (Parson) on Jun 02, 2015 at 18:14 UTC
As it happens, the @ notation is used by several code documentation "generators". A somewhat popular one is Doxygen. You might want to look at its notations for the purpose of making your usage compatable. Also, as I recently discovered, the Perl6 project has extended POD syntax to include similar comments as code annotations, using `#\|` or `#=` to introduce these annotations. However, the markup in these comments is "just" more POD. However, it validates the concept you are proposing. There is a module that partially implements Perl6 POD syntax, but it appears to not implement `#\|` and `#=` comments. If this is the case, I am considering enhancing it. FWIW, I am working on a Doxygen to POD filter. An early version is Convert Doxygen to POD. Update: Fixed a grammar error.	[reply] [d/l] [select]
Re^2: Annotations for Perl by hurricup (Pilgrim) on Jun 03, 2015 at 05:47 UTC
If i'm going to use documentation injections, it would be pod with =for i believe, not another documentation system.	[reply]
Re^3: Annotations for Perl by RonW (Parson) on Jun 03, 2015 at 15:46 UTC
I'm just suggesting that if you are going to use @ comments to inject metadata about the source code, it makes sense to do so in a way compatible with document generation tools. That way the generator can re-use the metadata without need to repeat it in your POD markup. BTW, my filter supports `=for` for @ notations while passing other POD markup through, unmodified.	[reply] [d/l]
Re: Annotations for Perl by fishmonger (Chaplain) on Jun 02, 2015 at 16:32 UTC
I might be missing something and thereby not understanding your intent, but ~~what's wrong with using~~ why not use POD documentation?	[reply]
Re^2: Annotations for Perl by hurricup (Pilgrim) on Jun 02, 2015 at 16:38 UTC
To use pod, i need to make strict rules, how to write it so IDE parser could interpret it. And those rules should not break the html compiled pod And pod is for human reading i belive, not machine.	[reply]
Re^3: Annotations for Perl by Anonymous Monk on Jun 02, 2015 at 16:54 UTC
POD's `=for` might help there, e.g. `=for ide @Returns Foo::Bar` [download] AFAIK POD parsers will ignore that if they don't recognize "ide", but your parser could pull those out.	[reply] [d/l] [select]
Re^4: Annotations for Perl by hurricup (Pilgrim) on Jun 02, 2015 at 17:31 UTC
Re^5: Annotations for Perl by Anonymous Monk on Jun 02, 2015 at 23:56 UTC
Some notes below your chosen depth have not been shown here
Re^5: Annotations for Perl by Anonymous Monk on Jun 02, 2015 at 22:21 UTC
Re: Annotations for Perl by LanX (Saint) on Jun 06, 2015 at 12:33 UTC
Another option are attributes. update: see Attribute::Handlers Cheers Rolf _{(addicted to the Perl Programming Language and ☆☆☆☆ :) Je suis Charlie!}	[reply]
Re: Annotations for Perl by Anonymous Monk on Jun 02, 2015 at 22:52 UTC
Of course, it's possible to constantly work on smart algorythms, which will be able to analyse previous sub in "dereference" chain and try to guess, what was returned. But it's an endless work as a Perl itself and resourse-consuming. Sure, if you try to write it in Java. If you write it in perl its considerably easier, PPI, http://deps.cpantesters.org/depended-on-by.pl?dist=PPI-1.220, Pod::Coverage::Moose, Devel::Cover, Devel::PerlySense	[reply]
Re^2: Annotations for Perl by hurricup (Pilgrim) on Jun 03, 2015 at 05:46 UTC
Do you know how to write IDEA plugin in language other than Java?	[reply]
Re^3: Annotations for Perl by Anonymous Monk on Jun 03, 2015 at 08:08 UTC
Do you know how to write IDEA plugin in language other than Java? Nope. But you don't have to write all the https://github.com/hurricup/Perl5-IDEA/blob/master/src/com/perl5/lang/perl/lexer/Perl.flex stuff in java. Your plugin could call "perl lexmyperlfile.pl" via Runtime.getRuntime().exec() or some such Or if that is too slow, open a socket and launch "perl threrealplugin.pl" so they can talk on this socket Instead of doing all the hard work yourself, let CPAN work for you somehow or something ... its just ideas :)	[reply]
Re^4: Annotations for Perl by hurricup (Pilgrim) on Jun 03, 2015 at 08:47 UTC
Re: Annotations for Perl by Anonymous Monk on Jun 02, 2015 at 22:11 UTC
Really need a feedback and ideas. Seems like a dead end that gets in the way of work :) much like Rinci/ Perinci	[reply]
Re^2: Annotations for Perl by hurricup (Pilgrim) on Jun 03, 2015 at 05:48 UTC
Not sure I've understood your point	[reply]
Re^3: Annotations for Perl by RonW (Parson) on Jun 03, 2015 at 16:28 UTC
The AM is overlooking the fact that you are trying to provide information about your source code that other languages, such as Java, require as part of the source code, but Perl does not allow (except in comments) Your concept is good. Providing this metadata is good.	[reply]
Re^3: Annotations for Perl by Anonymous Monk on Jun 03, 2015 at 07:53 UTC
Not sure I've understood your point Think of it like a joke :)	[reply]
Re: Annotations for Perl by hurricup (Pilgrim) on Jun 03, 2015 at 13:35 UTC
I belive it's not bad after all...	[reply]
Re: Annotations for Perl by LanX (Saint) on Jun 06, 2015 at 04:12 UTC
Use the force, Luke! ;-) `sub somefunc{ my Foo::Bar $ret; # documentation ... return $ret; }` [download] Cheers Rolf _{(addicted to the Perl Programming Language and ☆☆☆☆ :) Je suis Charlie!}	[reply] [d/l]