From 02645507b1ae3d9422f453568f4e1a732e18f5e7 Mon Sep 17 00:00:00 2001
From: Jesse Luehrs <doy@tozt.net>
Date: Sun, 24 Jun 2018 13:08:41 -0400
Subject: docs

---
 lib/WWW/YNAB.pm | 143 +++++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 142 insertions(+), 1 deletion(-)

(limited to 'lib/WWW/YNAB.pm')

diff --git a/lib/WWW/YNAB.pm b/lib/WWW/YNAB.pm
index 74d0f4d..113662a 100644
--- a/lib/WWW/YNAB.pm
+++ b/lib/WWW/YNAB.pm
@@ -1,6 +1,6 @@
 package WWW::YNAB;
-use Moose;
 
+use Moose;
 # ABSTRACT: Wrapper for the YNAB API
 
 use WWW::YNAB::Account;
@@ -18,18 +18,55 @@ use WWW::YNAB::User;
 
 with 'WWW::YNAB::ModelHelpers';
 
+=head1 SYNOPSIS
+
+  use WWW::YNAB;
+
+  my $ynab = WWW::YNAB->new(access_token => 'SECRET');
+  my @budgets = $ynab->budgets;
+
+=head1 DESCRIPTION
+
+This module is a wrapper around the V1 YNAB API. It follows the API structure
+quite closely, so the API documentation should be used for information about
+the data that this module returns. You can find the API documentation at L<https://api.youneedabudget.com/>.
+
+=cut
+
+=attr access_token
+
+Your personal access token. Information about generating a personal access
+token can be found at
+L<https://api.youneedabudget.com/#personal-access-tokens>. Required.
+
+=cut
+
 has access_token => (
     is       => 'ro',
     isa      => 'Str',
     required => 1,
 );
 
+=attr base_uri
+
+The base uri for all API requests. Defaults to
+C<https://api.youneedabudget.com/v1/>. It's unlikely you'll need to change
+this.
+
+=cut
+
 has base_uri => (
     is      => 'ro',
     isa     => 'Str',
     default => 'https://api.youneedabudget.com/v1/',
 );
 
+=attr ua
+
+The HTTP user agent to use. Must be compatible with L<HTTP::Tiny>.
+
+=cut
+
 has ua => (
     is      => 'ro',
     isa     => 'HTTP::Tiny',
@@ -51,6 +88,10 @@ has _ua => (
     },
 );
 
+=method user
+
+=cut
+
 sub user {
     my $self = shift;
 
@@ -59,6 +100,10 @@ sub user {
     $self->model_from_data('WWW::YNAB::User', $user);
 }
 
+=method budgets
+
+=cut
+
 sub budgets {
     my $self = shift;
 
@@ -68,6 +113,17 @@ sub budgets {
     } @{ $data->{data}{budgets} };
 }
 
+=method budget($id, $server_knowledge=undef)
+
+Returns the budget with id C<$id>. The returned budget object will have a
+C<server_knowledge> method which represents the state of the server when that
+object was returned. If the C<$server_knowledge> parameter is passed here with
+a value that came from an object previously returned by this method, this
+method will only return sub-objects (transactions, accounts, etc.) which have
+changed since that previous object was generated.
+
+=cut
+
 sub budget {
     my $self = shift;
     my ($id, $server_knowledge) = @_;
@@ -192,24 +248,53 @@ sub budget {
     );
 }
 
+=method rate_limit
+
+Returns the number of requests in the current rate limit bucket.
+
+=cut
+
 sub rate_limit {
     my $self = shift;
 
     $self->_ua->rate_limit
 }
 
+=method knows_rate_limit
+
+Returns true if the current rate limit is known. This will only be true after a
+request has already been made (since the API currently doesn't provide a way to
+just request the current rate limit).
+
+=cut
+
 sub knows_rate_limit {
     my $self = shift;
 
     $self->_ua->knows_rate_limit
 }
 
+=method total_rate_limit
+
+Returns the total number of requests that will be allowed in the current rate
+limit bucket.
+
+=cut
+
 sub total_rate_limit {
     my $self = shift;
 
     $self->_ua->total_rate_limit
 }
 
+=method knows_total_rate_limit
+
+Returns true if the current total rate limit is known. This will only be true
+after a request has already been made (since the API currently doesn't provide
+a way to just request the current rate limit).
+
+=cut
+
 sub knows_total_rate_limit {
     my $self = shift;
 
@@ -219,4 +304,60 @@ sub knows_total_rate_limit {
 __PACKAGE__->meta->make_immutable;
 no Moose;
 
+=head1 BUGS/LIMITATIONS
+
+No known bugs.
+
+Please report any bugs to GitHub Issues at
+L<https://github.com/doy/www-ynab/issues>.
+
+Not all of the API is exposed by this wrapper yet. In particular, these things
+are missing:
+
+=over 4
+
+=item All modification endpoints (this module currently only exposes read-only operations)
+
+=item The payee location API
+
+=item OAuth authentication
+
+=back
+
+Patches are greatly appreciated if you are interested in this functionality.
+
+=head1 SEE ALSO
+
+L<https://api.youneedabudget.com/>
+
+=head1 SUPPORT
+
+You can find this documentation for this module with the perldoc command.
+
+    perldoc WWW::YNAB
+
+You can also look for information at:
+
+=over 4
+
+=item * MetaCPAN
+
+L<https://metacpan.org/release/WWW-YNAB>
+
+=item * Github
+
+L<https://github.com/doy/www-ynab>
+
+=item * RT: CPAN's request tracker
+
+L<http://rt.cpan.org/NoAuth/Bugs.html?Dist=WWW-YNAB>
+
+=item * CPAN Ratings
+
+L<http://cpanratings.perl.org/d/WWW-YNAB>
+
+=back
+
+=cut
+
 1;
-- 
cgit v1.2.3-54-g00ecf