From ae29ae0ebf66ec84b2762006a1189073cc759a08 Mon Sep 17 00:00:00 2001
From: Yanick Champoux <yanick@cpan.org>
Date: Mon, 25 Jul 2022 11:21:03 -0400
Subject: [PATCH] doc for ::Print

---
 lib/App/Changelord.pm                | 48 +++++++++++++++-------------
 lib/App/Changelord/Command/Print.pm  | 29 +++++++++++++++++
 lib/App/Changelord/Role/Changelog.pm | 21 ++++++++++++
 t/basic.t                            |  4 +--
 4 files changed, 77 insertions(+), 25 deletions(-)
 create mode 100644 lib/App/Changelord/Command/Print.pm
 create mode 100644 lib/App/Changelord/Role/Changelog.pm

diff --git a/lib/App/Changelord.pm b/lib/App/Changelord.pm
index 3c2d1bf..e97fde0 100644
--- a/lib/App/Changelord.pm
+++ b/lib/App/Changelord.pm
@@ -1,39 +1,41 @@
 package App::Changelord;
+# SYNOPSIS: cli-based changelog manager
 
 # version next latest
 
 use 5.36.0;
 
 use Moo;
-use CLI::Osprey;
+use CLI::Osprey
+    desc => 'changelog manager';
+
 use YAML;
 
 use List::AllUtils qw/ pairmap partition_by /;
 
 use App::Changelord::Role::ChangeTypes;
 
-option source => (
-    is => 'ro',
-    format => 's',
-    doc => 'changelog yaml file',
-    default => 'CHANGELOG.yml',
-);
-
-has changelog => ( is => 'lazy' );
-
-sub _build_changelog($self) {
-    return YAML::LoadFile($self->source)
-}
-
-with 'App::Changelord::Role::ChangeTypes';
-with 'App::Changelord::Role::Render';
-
-sub run($self) {
-    no warnings 'utf8';
-    print $self->as_markdown;
-}
-
 subcommand $_ => 'App::Changelord::Command::' . ucfirst $_ =~ s/-(.)/uc $1/er
-    for qw/ schema validate version bump init add git-gather /;
+    for qw/ schema validate version bump init add git-gather print /;
 
 1;
+
+__END__
+
+=head1 DESCRIPTION
+
+C<App::Changelord> offers a collection of cli commands to
+interact with a YAML-based CHANGELOG file format, from which
+a Markdown CHANGELOG fit for general comsumption can be generated.
+
+See the original blog entry in the C<SEE ALSO> section for the full
+motivation.
+
+For a list of the commands, C<changelord --help>, then to
+get information on the individual commands C<changelord *subcommand* --man>.
+
+=head1 SEE ALSO
+
+L<Changelord, registrar of deeds extraordinaire|https://techblog.babyl.ca/entry/changelord> - the introducing blog entry.
+
+
diff --git a/lib/App/Changelord/Command/Print.pm b/lib/App/Changelord/Command/Print.pm
new file mode 100644
index 0000000..ba6b240
--- /dev/null
+++ b/lib/App/Changelord/Command/Print.pm
@@ -0,0 +1,29 @@
+package App::Changelord::Command::Print;
+
+use 5.36.0;
+
+use Moo;
+use CLI::Osprey
+    desc => 'print the changelog',
+    description_pod => <<'END';
+Render the full changelog. The default is to render the changelog
+in markdow, but the option C<--json> can be used to have a JSON
+version instead.
+END
+
+with 'App::Changelord::Role::Changelog';
+with 'App::Changelord::Role::ChangeTypes';
+with 'App::Changelord::Role::Render';
+
+option json => (
+    is => 'ro',
+    default => 0,
+    doc => 'output schema as json',
+);
+
+sub run($self) {
+    no warnings 'utf8';
+    print $self->as_markdown;
+}
+
+'end of App::Changelog::Command::Print';
diff --git a/lib/App/Changelord/Role/Changelog.pm b/lib/App/Changelord/Role/Changelog.pm
new file mode 100644
index 0000000..cc6d49a
--- /dev/null
+++ b/lib/App/Changelord/Role/Changelog.pm
@@ -0,0 +1,21 @@
+package App::Changelord::Role::Changelog;
+
+use v5.36.0;
+
+use Moo::Role;
+use CLI::Osprey;
+
+option source => (
+    is => 'ro',
+    format => 's',
+    doc => q{changelog yaml file. Defaults to the env variable $CHANGELOG, or 'CHANGELOG.yml'},
+    default => $ENV{CHANGELOG} || 'CHANGELOG.yml',
+);
+
+has changelog => ( is => 'lazy' );
+
+sub _build_changelog($self) {
+    return YAML::LoadFile($self->source)
+}
+
+1;
diff --git a/t/basic.t b/t/basic.t
index 8781320..9129100 100644
--- a/t/basic.t
+++ b/t/basic.t
@@ -2,9 +2,9 @@ use 5.36.0;
 
 use Test2::V0;
 
-use App::Changelord;
+use App::Changelord::Command::Print;
 
-my $change = App::Changelord->new(
+my $change = App::Changelord::Command::Print->new(
     changelog => {
         project => { name => 'Foo' },
     }