=head1 NAME

Devel::PerlySense::Document::Api::Method - A method/sub


An Api::Method is a sub name and a location (possibly with a defined
row, etc).

The Method has a documentation string and possibly POD.


use strict;
use warnings;

package Devel::PerlySense::Document::Api::Method;
  $Devel::PerlySense::Document::Api::Method::VERSION = '0.0197';

use Spiffy -Base;
use Carp;
use Data::Dumper;
use List::Util qw/ first /;

use Devel::PerlySense::Document::Api;
use Devel::PerlySense::Document::Location;


=head2 name

The method name

Default: "".

field "name" => "";

=head2 oLocationDocumented

A Document::Location object specifying where the method is documented,
or undef if that is unknown.

Default: undef.

field "oLocationDocumented" => undef;

=head2 oDocument

A PerlySense::Document object specifying in which the method belongs
to. This does not have to be the Document where it's declared.

Default: undef.

field "oDocument" => undef;

=head2 signature

Return doc string with the signature of the method, according to found
documentation, usage, etc.


sub signature {

    my $signature = $self->name;
    my $nameMethod = $self->name;
    if(my $oLocation = $self->oLocationDocumented) {
        my @aTextPod = split(/\n/, $oLocation->rhProperty->{text});
        $signature =
                first( sub { /->\s*\b$nameMethod\b/ }, @aTextPod )
             || first( sub { /\b$nameMethod\b/      }, @aTextPod )
             || $signature;

    $signature =~ s/ .* (\b$nameMethod\b) /$1/x;
    $signature =~ s/^ \s+ | \s* ; \s* $//gx;

    return $signature;


=head2 new(oDocument, name)

Create new Method with $name belonging to $oDocument.

Set oLocationDocumented according to the found documentation.

sub new(@) {
    my $pkg = shift;
    my (%p) = @_;

    my $self = bless {}, $pkg;
    $self->name($p{name}) or croak("Missing parameter name\n");
    $self->oDocument($p{oDocument}) or croak("Missing parameter oDocument\n");


=head2 signatureCall($oLocationDeclaration)

Return doc string with the call signature of the method, according to
the $oLocationDeclaration, etc.

The call signature is the signature with a call arrow, either -> or \>

sub signatureCall {
    my ($oLocationDeclaration) = @_;
    my $signature = $self->signature;

    my $prefixCall = $self->oDocument->file eq $oLocationDeclaration->file ? '->' : '\>';

    return "$prefixCall$signature";



=head1 AUTHOR

Johan Lindström, C<< <johanl[ÄT]DarSerMan.com> >>

=head1 BUGS

Please report any bugs or feature requests to
C<bug-devel-perlysense@rt.cpan.org>, or through the web interface at
I will be notified, and then you'll automatically be notified of progress on
your bug as I make changes.



Copyright 2005 Johan Lindström, All Rights Reserved.

This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.