Helping EPIC guess types tip

2008-11-10
2013-05-20
  • 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...

     
    • Jan Ploski
      Jan Ploski
      2008-11-10

      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.