Helping EPIC guess types tip

gord wrote on Mon Nov 10 14:41:14 CET 2008:

I have found that if you have a bless reference coming
in to a sub the following comment will help EPIC guess the
type. 

# Get the parameter and tell EPIC the type
#
my $obj = shift;       # $obj = OurProduct::MyClass::

$obj->[Ctrl-Space here will bring the correct methods up for the MyClass
type]

I do not know if this is a feature or just a side-effect
of the implementation that already works to pick up
the type from my $obj = Class::new() but I thought I would share it - 
perhaps also in the hope that it does not go away.

Any other such tips?

(e.g. I am just about to look at customising perldoc)

Gordon...

jploski wrote on Mon Nov 10 18:43:20 CET 2008:

This is a side effect of the implementation. It has been in EPIC for years
now, so on that basis you may assume it won't go away (no guarantees though).

Regarding perldoc, I agree that it would be nice to have a convention to
aid EPIC (and programmers) in type recognition, but I am unaware of anything
that one could call an established standard. This is perhaps due to the
general philosophy of perldoc as a free-form, between-the-lines, reader-friendly
description rather than a semi-formal tool-friendly specification.

Personally, I don't use perldoc, but instead rely on Javadoc-like syntax
conventions, e.g.

# Find the birth date for a given person
#
# @param name   name of a person
# @param id     (optional) person's id
# @return birth date in format yyyy-mm-dd
sub get_birthday
{
    my $name = shift;
    my $id = shift;

   ...

   return $birthday;
}

This convention obviously contains no type information, but it could be
inserted in front of the parameter's name after @param, for example. Then
it could be picked up by EPIC (other features which can use such description
is hover-on documentation and parameter completion). However, an additional
problem is hash-style parameter passing (where the keys of a hash are the
actual items that need documenting), which of course can be done in two
ways ({ param => value } or just param => value) and mixed with normal positional
parameters.

Of course the downside of such Javadoc-like conventions is that the standard
perldoc tool no longer applies.

Perl 6 type annotations could also become a possible basis, but who knows
when Perl 6 will be released and widely available.

If you come up with a really good set of conventions, I encourage you to
write them up (maybe first checking around the web what other people have
invented), and the specification could be implemented in EPIC some day.