From de72f280ecfd277f66c347a12c965893b1cb2500 Mon Sep 17 00:00:00 2001
From: Jesse Luehrs <doy@tozt.net>
Date: Fri, 30 Apr 2010 17:45:24 -0500
Subject: docs

---
 lib/Carp/Always/Color.pm      | 31 ++++++++++++++++++++-----------
 lib/Carp/Always/Color/HTML.pm | 32 ++++++++++++++++++++++++++++++++
 lib/Carp/Always/Color/Term.pm | 32 ++++++++++++++++++++++++++++++++
 3 files changed, 84 insertions(+), 11 deletions(-)

diff --git a/lib/Carp/Always/Color.pm b/lib/Carp/Always/Color.pm
index 9c58978..00d9c1e 100644
--- a/lib/Carp/Always/Color.pm
+++ b/lib/Carp/Always/Color.pm
@@ -1,25 +1,33 @@
 package Carp::Always::Color;
+BEGIN {
+    if (-t *STDERR) {
+        require Carp::Always::Color::Term;
+    }
+    else {
+        require Carp::Always::Color::HTML;
+    }
+}
 
 =head1 NAME
 
-Carp::Always::Color -
+Carp::Always::Color - Carp::Always, but with color
 
 =head1 SYNOPSIS
 
+  use Carp::Always::Color;
 
-=head1 DESCRIPTION
+or
 
+  perl -MCarp::Always::Color -e'sub foo { die "foo" } foo()'
 
-=cut
+=head1 DESCRIPTION
 
-BEGIN {
-    if (-t *STDERR) {
-        require Carp::Always::Color::Term;
-    }
-    else {
-        require Carp::Always::Color::HTML;
-    }
-}
+Stack traces are hard to read when the messages wrap, because it's hard to tell
+when one message ends and the next message starts. This just colors the first
+line of each stacktrace, based on whether it's a warning or an error. If
+messages are being sent to a terminal, it colors them with terminal escape
+codes, otherwise it colors them with HTML (ideas for more intelligent behavior
+here are welcome).
 
 =head1 BUGS
 
@@ -31,6 +39,7 @@ L<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Carp-Always-Color>.
 
 =head1 SEE ALSO
 
+L<Carp::Always>
 
 =head1 SUPPORT
 
diff --git a/lib/Carp/Always/Color/HTML.pm b/lib/Carp/Always/Color/HTML.pm
index 04846ca..53b3f4e 100644
--- a/lib/Carp/Always/Color/HTML.pm
+++ b/lib/Carp/Always/Color/HTML.pm
@@ -1,6 +1,25 @@
 package Carp::Always::Color::HTML;
 use Carp::Always;
 
+=head1 NAME
+
+Carp::Always::Color::HTML - Carp::Always, but with HTML color
+
+=head1 SYNOPSIS
+
+  use Carp::Always::Color::HTML;
+
+or
+
+  perl -MCarp::Always::Color::HTML -e'sub foo { die "foo" } foo()'
+
+=head1 DESCRIPTION
+
+Like L<Carp::Always::Color>, but forces HTML coloring, regardless of where
+STDERR is pointing to.
+
+=cut
+
 BEGIN { $Carp::Internal{(__PACKAGE__)}++ }
 
 sub _die {
@@ -31,4 +50,17 @@ END {
     @SIG{qw(__DIE__ __WARN__)} = @OLD_SIG{qw(__DIE__ __WARN__)};
 }
 
+=head1 AUTHOR
+
+  Jesse Luehrs <doy at tozt dot net>
+
+=head1 COPYRIGHT AND LICENSE
+
+This software is copyright (c) 2010 by Jesse Luehrs.
+
+This is free software; you can redistribute it and/or modify it under
+the same terms as perl itself.
+
+=cut
+
 1;
diff --git a/lib/Carp/Always/Color/Term.pm b/lib/Carp/Always/Color/Term.pm
index 5b6b538..c4789f6 100644
--- a/lib/Carp/Always/Color/Term.pm
+++ b/lib/Carp/Always/Color/Term.pm
@@ -1,6 +1,25 @@
 package Carp::Always::Color::Term;
 use Carp::Always;
 
+=head1 NAME
+
+Carp::Always::Color::Term - Carp::Always, but with terminal color
+
+=head1 SYNOPSIS
+
+  use Carp::Always::Color::Term;
+
+or
+
+  perl -MCarp::Always::Color::Term -e'sub foo { die "foo" } foo()'
+
+=head1 DESCRIPTION
+
+Like L<Carp::Always::Color>, but forces ANSI terminal code coloring, regardless
+of where STDERR is pointing to.
+
+=cut
+
 BEGIN { $Carp::Internal{(__PACKAGE__)}++ }
 
 sub _die {
@@ -31,4 +50,17 @@ END {
     @SIG{qw(__DIE__ __WARN__)} = @OLD_SIG{qw(__DIE__ __WARN__)};
 }
 
+=head1 AUTHOR
+
+  Jesse Luehrs <doy at tozt dot net>
+
+=head1 COPYRIGHT AND LICENSE
+
+This software is copyright (c) 2010 by Jesse Luehrs.
+
+This is free software; you can redistribute it and/or modify it under
+the same terms as perl itself.
+
+=cut
+
 1;
-- 
cgit v1.2.3