More documentation!

lib/DDG/Block.pm

@@ -1,11 +1,5 @@
 package DDG::Block;
-
-=head1 DESCRIPTION
-
-This is the base class for the so called Block concept. Its mission is to allow a list of plugins to get used based on specific
-trigger types. As an extend you can see L<DDG::Block::Regexp> and L<DDG::Block::Words>.
-
-=cut
+# ABSTRACT: Block to bundle plugins with triggers
 
 use Moo::Role;
 use Carp;
@@ -15,9 +9,50 @@ requires qw(
 	request
 );
 
-=head1 ATTRIBUTES
+=head1 SYNOPSIS
+
+  package DDG::Block::MyType;
+
+  use Moo;
+  with qw( DDG::Block );
+
+  sub request { ... }
+
+  1;
+
+as another type of Block (not needed, checkout L<DDG::Block::Words> and L<DDG::Block::Regexp>).
+
+  my $block = DDG::Block::MyType->new( plugins => [qw(
+    DDG::Goodie::A
+    DDG::Goodie::B
+    DDG::Goodie::C
+  )] );
+
+or
 
-=head2 plugins
+  package DDG::Block::MyType::BlockA;
+
+  use Moo;
+  extends 'DDG::Block::MyType';
+
+  sub _build_plugins {[
+    DDG::Goodie::A
+    DDG::Goodie::B
+    DDG::Goodie::C
+  ]}
+
+  1;
+
+=head1 DESCRIPTION
+
+This is the L<Moo::Role> of the so called Block concept. Its mission is to allow a list of plugins to get used based on specific
+trigger types. As an extend you can see L<DDG::Block::Regexp> and L<DDG::Block::Words>.
+
+A class with B<DDG::Block> needs a B<request> function to handle a B<DDG::Request>. It gets as only parameter the request
+object and needs to return a list of results or an empty list. Dont forget that returning B<undef> on the request
+function means something depending of the context the B<DDG::Block> is used.
+
+=attr plugins
 
 The list of the plugins used for this block, its an array with a list of strings or hashes. A string defines a class which just
 gets regular instantiated via new, if you define a hash the parameter given in this hash are given to the instantiation process
@@ -34,7 +69,7 @@ has plugins => (
 
 sub _build_plugins { die (ref shift)." requires plugins" }
 
-=head2 return_one
+=attr return_one
 
 This attribute defines if the block should stop if there is a hit which gives a result. By default this is on.
 
@@ -46,7 +81,7 @@ has return_one => (
 	default => sub { 1 },
 );
 
-=head2 return_one
+=attr before_build
 
 A coderef that is executed before the build of the plugins. It gets the block object as first and the class name to instantiate
 as second parameter.
@@ -59,12 +94,30 @@ has before_build => (
 	predicate => 'has_before_build',
 );
 
+=attr after_build
+
+A coderef that is executed before the build of the plugins. It gets the block object as first and the object of the plugin
+as second parameter.
+
+=cut
+
 has after_build => (
 	#isa => 'CodeRef',
 	is => 'ro',
 	predicate => 'has_after_build',
 );
 
+=attr _plugin_objs B<private>
+
+This private attribute contains an array with an arrayref of trigger and plugin, its the main point where all subclasses
+of Blocks fetches the trigger => plugin definition. Do never set this attribute yourself, or you are doomed ;). The
+generation of this array also instantiates the plugins, which makes it an important point for the general handling
+plugins who needs B<after_build> and B<before_build>. It gets triggered on instantiation of the Block.
+
+The function goes through all plugin class names given on the setup of the blog
+
+=cut
+
 has _plugin_objs => (
 	# like ArrayRef[ArrayRef[$trigger,DDG::Block::Plugin]]',
 	is => 'ro',
@@ -118,6 +171,13 @@ sub _build__plugin_objs {
 	return \@plugin_objs;
 }
 
+=attr only_plugin_objs
+
+This read-only attribute contains an arrayref of all plugins in a row. This can be used to iterate over all objects
+more easy then using B<plugin_objs>. It gets generated only on usage and takes B<plugin_objs> as source.
+
+=cut
+
 has only_plugin_objs => (
 	is => 'ro',
 	lazy => 1,
@@ -132,15 +192,34 @@ sub _build_only_plugin_objs {
 	return \@plugins;
 }
 
+=method get_triggers_of_plugin
+
+This method will get called to find all the triggers given by a specific plugin. If your Block subclass requires
+a special handling here, then it can be overloaded and just behave like you require. It gets the object of the
+plugin as first parameter.
+
+=cut
+
 sub get_triggers_of_plugin { shift; shift->get_triggers }
 
+=method parse_trigger
+
+This method gets called for every single trigger of a plugin to parse out and sort out. By default it doesnt do
+anything, but as the other functions you can overload this behaviour.
+
+=cut
+
 sub parse_trigger { shift; shift; }
 
-sub empty_trigger { return undef }
+=method empty_trigger
 
-sub run_plugin {
-	my ( $self, $plugin, @args ) = @_;
-}
+This method gets called, if the plugin doesnt deliver any plugin, here you can wrap this to your own specific
+definition. Its so far only used in the L<DDG::Block::Words>, to disallow empty triggers totally. By default
+it returns B<undef>.
+
+=cut
+
+sub empty_trigger { return undef }
 
 sub BUILD {
 	my ( $self ) = @_;

lib/DDG/Goodie.pm

@@ -1,14 +1,15 @@
 package DDG::Goodie;
+# ABSTRACT: Goodie package for easy keywords
 
 use strict;
 use warnings;
 use Carp;
 use DDG::Meta;
-require Moo::Role;
 
 =head1 DESCRIPTION
 
 This is the Goodie Meta class. It injects all the keywords used for ZeroClickInfo Goodies.
+For more information see L<DDG::Meta>.
 
 =cut
 

lib/DDG/HasAttribution.pm

@@ -1,9 +1,22 @@
 package DDG::HasAttribution;
+# ABSTRACT: Role for a plugin that is able to give attribution informations
 
 use Moo::Role;
 
 requires qw(
 	get_attributions
 );
 
-1;
+=head1 DESCRIPTION
+
+This L<Moo::Role> is attached to plugins which are able to give attribution back. It
+still can be an empty attribution.
+
+The class using this role must implement a B<get_attributions> function which gives
+back the attribution array.
+
+For more information about the attributions see L<DDG::Meta::Attribution>.
+
+=cut
+
+1;

lib/DDG/HasShareDir.pm

@@ -1,4 +1,5 @@
 package DDG::HasShareDir;
+# ABSTRACT: Role for a plugin that has a share directory
 
 use Moo::Role;
 
@@ -7,4 +8,28 @@ requires qw(
 	share
 );
 
+=head1 DESCRIPTION
+
+This L<Moo::Role> is attached to plugins which are able to give sharedir informations.
+A class which has no sharedir is not allowed to carry this role.
+
+The class using this role must implement B<module_share_dir> and B<share>.
+
+B<module_share_dir> must return the path to the sharedir inside the repo, like:
+
+  share/goodie/public_dns
+
+B<share> must give back a L<Path::Class::Dir> of the share directory if its
+called without parameter. If a parameter is given it must give back L<Path::Class::File>
+or L<Path::Class::Dir> of the corresponding file in the sharedir that is given as
+parameter.
+
+For more information about the sharedir see L<DDG::Meta::ShareDir>.
+
+=head1 SEE ALSO
+
+L<Dist::Zilla::Plugin::AutoModuleShareDirs>
+
+=cut
+
 1;

lib/DDG/IsControllable.pm

@@ -1,4 +1,5 @@
 package DDG::IsControllable;
+# ABSTRACT: Role for data managed inside the DuckDuckGo infrastructure
 
 use Moo::Role;
 
@@ -17,4 +18,11 @@ has ttl => (
 	predicate => 'has_ttl',
 );
 
+=head1 DESCRIPTION
+
+This role is used for classes which should be cacheable or marked as safe or
+unsafe for kids.
+
+=cut
+
 1;

lib/DDG/IsGoodie.pm

@@ -1,9 +1,19 @@
 package DDG::IsGoodie;
+# ABSTRACT: Role for Goodies
 
 use Moo::Role;
 
 requires qw(
 	handle_request_matches
 );
 
+=head1
+
+This role is for plugins which are Goodies. They need to implement a
+B<handle_request_matches> function.
+
+Please see L<DDG::Meta::RequestHandler> and L<DDG::Meta> for more information.
+
+=cut
+
 1;

lib/DDG/IsSpice.pm

@@ -1,9 +1,19 @@
 package DDG::IsSpice;
+# ABSTRACT: Role for Spice
 
 use Moo::Role;
 
 requires qw(
 	handle_request_matches
 );
 
+=head1
+
+This role is for plugins which are Spice. They need to implement a
+B<handle_request_matches> function.
+
+Please see L<DDG::Meta::RequestHandler> and L<DDG::Meta> for more information.
+
+=cut
+
 1;

lib/DDG/Meta.pm

@@ -1,4 +1,5 @@
 package DDG::Meta;
+# ABSTRACT: Main meta layer implementation factory
 
 use strict;
 use warnings;
@@ -14,6 +15,29 @@ use	DDG::Meta::Helper;
 
 use MooX ();
 
+=head1 SYNOPSIS
+
+  DDG::Meta->apply_base_to_package("DDG::Goodie::MyGoodie");
+  DDG::Meta->apply_goodie_keywords("DDG::Goodie::MyGoodie");
+
+=head1 DESCRIPTION
+
+This package gathers all the functions to apply the meta
+layers used in DuckDuckGo. We try to apply easy keywords for
+the package developer, so that its most easy for the beginners
+to generate good plugins. This on the other side makes it
+right now hard to see what magic happens behind the curtains.
+L<DDG::Meta> functions shows up what is required to be some
+specific plugin on the DuckDuckGo module system.
+
+=method apply_base_to_package
+
+This function applies to the given target classname L<Moo> and L<Data::Printer>
+as if they were used directly inside the given classname. This is achieved
+with L<Import::Into> in combination with L<MooX>.
+
+=cut
+
 sub apply_base_to_package {
 	my ( $class, $target ) = @_;
 
@@ -22,6 +46,20 @@ sub apply_base_to_package {
 	));
 }
 
+=method apply_goodie_keywords
+
+This function applies a huge amount of keywords of other meta classes into
+the package of the given target classname. Please see:
+
+L<DDG::Meta::ZeroClickInfo>, L<DDG::Meta::ShareDir>, L<DDG::Meta::Block>,
+L<DDG::Meta::Attribution>, L<DDG::Meta::Helper>, L<DDG::Meta::Helper>,
+L<DDG::Meta::RequestHandler>
+
+The goodie request handler is supposed to give back an array of 
+L<DDG::ZeroClickInfo> objects or an empty array for nothing.
+
+=cut
+
 sub apply_goodie_keywords {
 	my ( $class, $target ) = @_;
 	DDG::Meta::ZeroClickInfo->apply_keywords($target);
@@ -37,6 +75,20 @@ sub apply_goodie_keywords {
 	},'DDG::IsGoodie');
 }
 
+=method apply_spice_keywords
+
+This function applies a huge amount of keywords of other meta classes into
+the package of the given target classname. Please see:
+
+L<DDG::Meta::ZeroClickInfoSpice>, L<DDG::Meta::ShareDir>, L<DDG::Meta::Block>,
+L<DDG::Meta::Attribution>, L<DDG::Meta::Helper>, L<DDG::Meta::Helper>,
+L<DDG::Meta::RequestHandler>
+
+The spice request handler is supposed to give back an array of 
+L<DDG::ZeroClickInfo::Spice> objects or an empty array for nothing.
+
+=cut
+
 sub apply_spice_keywords {
 	my ( $class, $target ) = @_;
 	DDG::Meta::ZeroClickInfoSpice->apply_keywords($target);