docs

1 files changed, 78 insertions, 0 deletions

diff --git a/lib/Dist/CheckConflicts.pm b/lib/Dist/CheckConflicts.pm
index d33a4a2..68c40a2 100644
--- a/lib/Dist/CheckConflicts.pm
+++ b/lib/Dist/CheckConflicts.pm
@@ -9,8 +9,73 @@ use Sub::Exporter;
 
 =head1 SYNOPSIS
 
+    use Dist::CheckConflicts
+        -dist => 'Class-MOP',
+        -conflicts => {
+            'Moose'                => '1.14',
+            'namespace::autoclean' => '0.08',
+        },
+        -also => [
+            'Package::Stash::Conflicts',
+        ];
+
+    __PACKAGE__->check_conflicts;
+
 =head1 DESCRIPTION
 
+One shortcoming of the CPAN clients that currently exist is that they have no
+way of specifying conflicting downstream dependencies of modules. This module
+attempts to work around this issue by allowing you to specify conflicting
+versions of modules separately, and deal with them after the module is done
+installing.
+
+For instance, say you have a module C<Foo>, and some other module C<Bar> uses
+C<Foo>. If C<Foo> were to change its API in a non-backwards-compatible way,
+this would cause C<Bar> to break until it is updated to use the new API. C<Foo>
+can't just depend on the fixed version of C<Bar>, because this will cause a
+circular dependency (because C<Bar> is already depending on C<Foo>), and this
+doesn't express intent properly anyway - C<Foo> doesn't use C<Bar> at all. The
+ideal solution would be for there to be a way to specify conflicting versions
+of modules in a way that would let CPAN clients update conflicting modules
+automatically after an existing module is upgraded, but until that happens,
+this module will allow users to do this manually.
+
+This module accepts a hash of options passed to its C<use> statement, with
+these keys being valid:
+
+=over 4
+
+=item -conflicts
+
+A hashref of conflict specifications, where keys are module names, and values
+are the last broken version - any version greater than the specified version
+should work.
+
+=item -also
+
+Additional modules to get conflicts from (potentially recursively). This should
+generally be a list of modules which use Dist::CheckConflicts, which correspond
+to the dists that your dist depends on. (In an ideal world, this would be
+intuited directly from your dependency list, but the dependency list isn't
+available outside of build time).
+
+=item -dist
+
+The name of the distribution, to make the error message from check_conflicts
+more user-friendly.
+
+=back
+
+The methods listed below are exported by this module into the module that uses
+it, so you should call these methods on your module, not Dist::CheckConflicts.
+
+As an example, this command line can be used to update your modules, after
+installing the C<Foo> dist (assuming that C<Foo::Conflicts> is the module in
+the C<Foo> dist which uses Dist::CheckConflicts):
+
+    perl -MFoo::Conflicts -e'print "$_\n"
+        for map { $_->{package} } Foo::Conflicts->calculate_conflicts' | cpanm
+
 =cut
 
 my $import = Sub::Exporter::build_exporter({
@@ -63,6 +128,9 @@ sub _strip_opt {
 
 =method conflicts
 
+Returns the conflict specification (the C<-conflicts> parameter to
+C<import()>), as a hash.
+
 =cut
 
 sub conflicts {
@@ -72,6 +140,9 @@ sub conflicts {
 
 =method dist
 
+Returns the dist name (either as specified by the C<-dist> parameter to
+C<import()>, or the package name which C<use>d this module).
+
 =cut
 
 sub dist {
@@ -81,6 +152,9 @@ sub dist {
 
 =method check_conflicts
 
+Examine the modules that are currently installed, and throw an exception with
+useful information if any modules are at versions which conflict with the dist.
+
 =cut
 
 sub check_conflicts {
@@ -100,6 +174,10 @@ sub check_conflicts {
 
 =method calculate_conflicts
 
+Examine the modules that are currently installed, and return a list of modules
+which conflict with the dist. The modules will be returned as a list of
+hashrefs, each containing C<package>, C<installed>, and C<required> keys.
+
 =cut
 
 sub calculate_conflicts {