Как работают атрибуты метода Perl?

Вы правы, документация не очень понятна в этой области, тем более что атрибуты не так сложны. Если вы определяете атрибут подпрограммы, например:

sub some_method :Foo { }

Perl будет при компиляции вашей программы (это важно) ищите магический sub MODIFY_CODE_ATTRIBUTES в текущем пакете или любом из его родительских классов. Это будет вызываться с именем текущего пакета, ссылкой на вашу подпрограмму и списком атрибутов, определенных для этой подпрограммы. Если этот обработчик не существует, компиляция завершится неудачно.

То, что вы делаете в этом обработчике, полностью зависит от вас. Да, это правильно. Никакой скрытой магии вообще. Если вы хотите сообщить об ошибке, то при возврате имени нарушающих атрибутов компиляция завершится с сообщением "недействительный атрибут".

Существует еще один обработчик, называемый FETCH_CODE_ATTRIBUTES, который будет вызываться всякий раз, когда кто-то говорит

use attributes;
my @attrs = attributes::get(\&some_method);

Этот обработчик получает переданное имя пакета и подпрограмму и должен возвращать список атрибутов подпрограммы (хотя то, что вы действительно делаете, снова зависит от вас).

Вот пример, чтобы включить простую "маркировку" методов с произвольными атрибутами, которые вы можете запросить позже:

package MyClass;
use Scalar::Util qw( refaddr );

my %attrs; # package variable to store attribute lists by coderef address

sub MODIFY_CODE_ATTRIBUTES {
    my ($package, $subref, @attrs) = @_;
    $attrs{ refaddr $subref } = \@attrs;
    return;
}

sub FETCH_CODE_ATTRIBUTES {
    my ($package, $subref) = @_;
    my $attrs = $attrs{ refaddr $subref };
    return @$attrs;
}

1;

Теперь в MyClass и во всех его подклассах вы можете использовать произвольные атрибуты и запрашивать их с помощью attributes::get():

package SomeClass;
use base 'MyClass';
use attributes;

# set attributes
sub hello :Foo :Bar { }

# query attributes
print "hello() in SomeClass has attributes: ",
      join ', ', attributes::get(SomeClass->can('hello'));

1;
__END__
hello() in SomeClass has attributes: Foo, Bar

В целом, атрибуты не делают очень многого, что, с другой стороны, делает их очень гибкими: вы можете использовать их в качестве реальных "атрибутов" (как показано в этом примере), реализовать что-то вроде декораторов (см. ответ Синан) или для ваших собственных коварных целей.