From 67b5bdf628482ba782d59e76c60588bbc79543b9 Mon Sep 17 00:00:00 2001 From: halorrr Date: Thu, 1 Feb 2024 14:02:57 -0500 Subject: [PATCH] add more examples to yard docs --- lib/lunchmoney/api.rb | 117 ++++++++++++++++++++++++++++++++++- lib/lunchmoney/calls/base.rb | 10 ++- 2 files changed, 124 insertions(+), 3 deletions(-) diff --git a/lib/lunchmoney/api.rb b/lib/lunchmoney/api.rb index 4052530..1a5bd4a 100644 --- a/lib/lunchmoney/api.rb +++ b/lib/lunchmoney/api.rb @@ -17,9 +17,12 @@ require_relative "calls/crypto" module LunchMoney - # The main API class that a user should interface through the method of any individual call is delegated through here + # The main API class that a user should interface through. The method of any individual call is delegated through here # so that it is never necessary to go through things like `LunchMoney::Calls::Users.new.user` instead you can directly # call the endpoint with LunchMoney::Api.new.user and it will be delegated to the correct call. + # @example + # api = LunchMoney::Api.new + # api.categories # This will be delegated to LunchMoney::Calls::Categories#categories class Api sig { returns(T.nilable(String)) } attr_reader :api_key @@ -31,6 +34,10 @@ def initialize(api_key: nil) delegate :me, to: :user_calls + # All [user call types](https://lunchmoney.dev/#user) come through here. + # @example [Get User](https://lunchmoney.dev/#get-user) + # api = LunchMoney::Api.new + # api.me sig { returns(LunchMoney::Calls::Base) } def user_calls with_valid_api_key do @@ -48,6 +55,32 @@ def user_calls :force_delete_category, to: :category_calls + # All [category call types](https://lunchmoney.dev/#categories) come through here. Reference the docs for + # available parameters for each call + # @example [Get All Categories](https://lunchmoney.dev/#get-all-categories) + # api = LunchMoney::Api.new + # api.categories + # @example [Get Single Category](https://lunchmoney.dev/#get-single-category) + # api = LunchMoney::Api.new + # api.category(1234567) + # @example [Create Category](https://lunchmoney.dev/#create-category) + # api = LunchMoney::Api.new + # api.create_category(name: "New Category Name") + # @example [Create Category Group](https://lunchmoney.dev/#create-category-group) + # api = LunchMoney::Api.new + # api.create_category_group(name: "New Category Group Name") + # @example [Update Category](https://lunchmoney.dev/#update-category) + # api = LunchMoney::Api.new + # api.update_category(1234567, "Updated Category Name") + # @example [Add to Category Group](https://lunchmoney.dev/#add-to-category-group) + # api = LunchMoney::Api.new + # api.add_to_category_group(7654321, category_ids: [1234567], new_categories: ["Another Category"]) + # @example [Delete Category](https://lunchmoney.dev/#delete-category) + # api = LunchMoney::Api.new + # api.delete_category(1234567) + # @example [Force Delete Category](https://lunchmoney.dev/#force-delete-category) + # api = LunchMoney::Api.new + # api.force_delete_category(1234567) sig { returns(LunchMoney::Calls::Base) } def category_calls with_valid_api_key do @@ -57,6 +90,10 @@ def category_calls delegate :tags, to: :tag_calls + # All [tags call types](https://lunchmoney.dev/#tags) come through here. + # @example [Get All Tags](https://lunchmoney.dev/#get-all-tags) + # api = LunchMoney::Api.new + # api.tags sig { returns(LunchMoney::Calls::Base) } def tag_calls with_valid_api_key do @@ -74,6 +111,52 @@ def tag_calls :delete_transaction_group, to: :transaction_calls + # All [transaction call types](https://lunchmoney.dev/#transactions) come through here. + # @example [Get All Transactions](https://lunchmoney.dev/#get-all-transactions) + # api = LunchMoney::Api.new + # api.transactions + # @example [Get Single Transaction](https://lunchmoney.dev/#get-single-transaction) + # api = LunchMoney::Api.new + # api.transaction(123456789) + # @example [Insert Transactions](https://lunchmoney.dev/#insert-transactions) + # api = LunchMoney::Api.new + # transaction = LunchMoney::Objects::UpdateTransaction.new( + # date: "2024-01-01", + # amount: "10.99", + # payee: "Example Payee", + # currency: "cad", + # status: "cleared" + # ) + # api.insert_transactions([transaction]) + # @example Regular [Update Transactions](https://lunchmoney.dev/#update-transactions) + # api = LunchMoney::Api.new + # transaction = LunchMoney::Objects::UpdateTransaction.new( + # date: "2024-01-01", + # amount: "10.99", + # payee: "Example Payee", + # currency: "cad", + # status: "cleared" + # ) + # api.update_transaction(123456789, transaction: transaction) + # @example Split [Update Transactions](https://lunchmoney.dev/#update-transactions) + # api = LunchMoney::Api.new + # split = [ + # LunchMoney::Objects::Split.new(amount: "10.00"), + # LunchMoney::Objects::Split.new(amount: "47.54"), + # ] + # api.update_transaction(12345678, split: split) + # @example [Unsplit Transactions](https://lunchmoney.dev/#unsplit-transactions) + # api = LunchMoney::Api.new + # api.unsplit_transaction([123456789]) + # @example [Get Transaction Group](https://lunchmoney.dev/#get-transaction-group) + # api = LunchMoney::Api.new + # api.transaction_group(987654321) + # @example [Create Transaction Group](https://lunchmoney.dev/#create-transaction-group) + # api = LunchMoney::Api.new + # api.create_transaction_group(date: "2024-01-01", payee: "Group", transactions: [123456789, 987654321]) + # @example [Delete Transaction Group](https://lunchmoney.dev/#delete-transaction-group) + # api = LunchMoney::Api.new + # api.delete_transaction_group(905483362) sig { returns(LunchMoney::Calls::Base) } def transaction_calls with_valid_api_key do @@ -86,6 +169,10 @@ def transaction_calls delegate :recurring_expenses, to: :recurring_expense_calls + # All [recurring expenses call types](https://lunchmoney.dev/#recurring-expenses) come through here. + # @example [Get Recurring Expenses](https://lunchmoney.dev/#get-recurring-expenses) + # api = LunchMoney::Api.new + # api.recurring_expenses sig { returns(LunchMoney::Calls::Base) } def recurring_expense_calls with_valid_api_key do @@ -98,6 +185,16 @@ def recurring_expense_calls delegate :budgets, :upsert_budget, :remove_budget, to: :budget_calls + # All [budget call types](https://lunchmoney.dev/#budget) come through here. + # @example [Get Budget Summary](https://lunchmoney.dev/#get-budget-summary) + # api = LunchMoney::Api.new + # api.budgets(start_date: "2023-01-01", end_date: "2024-01-01") + # @example [Upsert Budget](https://lunchmoney.dev/#upsert-budget) + # api = LunchMoney::Api.new + # api.upsert_budget(start_date: "2023-01-01", category_id: 777052, amount: 400.99) + # @example [Remove Budget(https://lunchmoney.dev/#remove-budget) + # api = LunchMoney::Api.new + # api.remove_budget(start_date: "2023-01-01", category_id: 777052) sig { returns(LunchMoney::Calls::Base) } def budget_calls with_valid_api_key do @@ -107,6 +204,10 @@ def budget_calls delegate :assets, :create_asset, :update_asset, to: :asset_calls + # All [assets call types](https://lunchmoney.dev/#assets) come through here. + # @example [Get All Assets](https://lunchmoney.dev/#get-all-assets) + # api = LunchMoney::Api.new + # api.assets sig { returns(LunchMoney::Calls::Base) } def asset_calls with_valid_api_key do @@ -116,6 +217,13 @@ def asset_calls delegate :plaid_accounts, :plaid_accounts_fetch, to: :plaid_account_calls + # All [Plaid accounts call types](https://lunchmoney.dev/#plaid-accounts) come through here. + # @example [Get All Plaid Accounts](https://lunchmoney.dev/#get-all-plaid-accounts) + # api = LunchMoney::Api.new + # api.plaid_accounts + # @example [Trigger Fetch from Plaid](https://lunchmoney.dev/#trigger-fetch-from-plaid) + # api = LunchMoney::Api.new + # api.plaid_accounts_fetch sig { returns(LunchMoney::Calls::Base) } def plaid_account_calls with_valid_api_key do @@ -128,6 +236,13 @@ def plaid_account_calls delegate :crypto, :update_crypto, to: :crypto_calls + # All [crypto call types](https://lunchmoney.dev/#crypto) come through here. + # @example [Get All Crypto](https://lunchmoney.dev/#get-all-crypto) + # api = LunchMoney::Api.new + # api.crypto + # @example [Update Manual Crypto Asset](https://lunchmoney.dev/#update-manual-crypto-asset) + # api = LunchMoney::Api.new + # api.update_crypto(1234567, name: "New Crypto Name") sig { returns(LunchMoney::Calls::Base) } def crypto_calls with_valid_api_key do diff --git a/lib/lunchmoney/calls/base.rb b/lib/lunchmoney/calls/base.rb index 16d7a1c..0775a1d 100644 --- a/lib/lunchmoney/calls/base.rb +++ b/lib/lunchmoney/calls/base.rb @@ -4,9 +4,15 @@ require_relative "../errors" module LunchMoney - # Namespace for API call classes + # Namespace for all API call classes. The methods on these classes should not typically be accessed directly. + # Instead they should be accessed through `LunchMoney::Api` instances, which will handle delegating the methods to + # the appropriate Calls class. + # @example + # api = LunchMoney::Api.new + # api.categories # This will be delegated to LunchMoney::Calls::Categories#categories module Calls - # Base class for all API call types + # Base class for all API call types. Containing the base methods got HTTP call types like GET / POST / PUT / DELETE + # as well as the general error handler class Base # Base URL used for API calls BASE_URL = "https://dev.lunchmoney.app/v1/"