improving documentation

EodHistoricalData · Jun 4, 2024 · dd0fe8d · dd0fe8d
1 parent 73816ee
commit dd0fe8d
Show file tree

Hide file tree

Showing 13 changed files with 51 additions and 41 deletions.
diff --git a/R/base-query.R b/R/base-query.R
@@ -1,4 +1,4 @@
-#' Low level (unexported) function for fetching data from API
+#' Low level (unexported) function for retrieving data from API
 #'
 #' @param url A well formed url
 #'

diff --git a/R/dividends.R b/R/dividends.R
@@ -19,7 +19,7 @@ get_dividends <- function(ticker = "AAPL", exchange = "US",
                           cache_folder = get_default_cache(),
                           check_quota = TRUE) {
 
-  cli::cli_h1("fetching dividends for ticker {ticker}|{exchange}")
+  cli::cli_h1("retrieving dividends for ticker {ticker}|{exchange}")
 
   if (check_quota) {
     get_quota_status()

diff --git a/R/exchanges.R b/R/exchanges.R
@@ -13,7 +13,7 @@
 #'
 get_exchanges <- function() {
 
-  cli::cli_h1("fetching exchange list")
+  cli::cli_h1("retrieving exchange list")
 
   token <- get_token()
   if (token == get_demo_token()) {

diff --git a/R/fundamentals.R b/R/fundamentals.R
@@ -28,7 +28,7 @@ get_fundamentals <- function(ticker = "AAPL",
                              cache_folder = get_default_cache(),
                              check_quota = TRUE) {
 
-  cli::cli_h1("fetching fundamentals for ticker {ticker}|{exchange}")
+  cli::cli_h1("retrieving fundamentals for ticker {ticker}|{exchange}")
 
   token <- get_token()
 

diff --git a/R/prices.R b/R/prices.R
@@ -15,7 +15,7 @@ get_prices <- function(ticker = "AAPL",
                        cache_folder = get_default_cache(),
                        check_quota = TRUE) {
 
-  cli::cli_h1("fetching price data for ticker {ticker}|{exchange}")
+  cli::cli_h1("retrieving price data for ticker {ticker}|{exchange}")
 
     if (check_quota) {
     get_quota_status()

diff --git a/R/splits.R b/R/splits.R
@@ -19,7 +19,7 @@ get_splits <- function(ticker = "AAPL", exchange = "US",
     cli::cli_abort("You need a proper token (not demonstration) for exchange list..")
   }
 
-  cli::cli_alert_info("fetching splits for ticker {ticker}|{exchange}")
+  cli::cli_h1("retrieving splits for ticker {ticker}|{exchange}")
 
   if (check_quota) {
     get_quota_status()

diff --git a/R/tickers.R b/R/tickers.R
@@ -16,7 +16,7 @@ get_tickers <- function(exchange = "US") {
     cli::cli_abort("You need a proper token (not demonstration) for the ticker list..")
   }
 
-  cli::cli_alert_info("fetching tickers for {exchange}")
+  cli::cli_h1("retrieving tickers for {exchange}")
 
   url <- glue::glue('{get_base_url()}/exchange-symbol-list/{exchange}?api_token={token}&fmt=json')
 

diff --git a/R/token.R b/R/token.R
@@ -33,8 +33,8 @@ set_token <- function(token = get_demo_token()) {
 
   if (token == get_demo_token()) {
     cli::cli_alert_danger(
-      "You are using a DEMONSTRATION token for testing pourposes, with limited access to the data repositories.
-      See <https://eodhd.com/> for registration and use function set_token(TOKEN) to set your own token.")
+      "You are using a **DEMONSTRATION** token for testing pourposes, with limited access to the data repositories.
+      See <https://eodhd.com/> for registration and, after finding your token, use it with function eodhd2::set_token(TOKEN).")
   }
 
   return(invisible(TRUE))
@@ -57,7 +57,7 @@ get_token <- function() {
   token <- Sys.getenv("eodhd-token")
 
   if (token == "") {
-    cli::cli_abort("Cant find token. Set your token with function eodhd2::set_token()")
+    cli::cli_abort("Can't find eodhd token. Set your token with function eodhd2::set_token()")
   }
 
   return(token)

diff --git a/README.Rmd b/README.Rmd
@@ -22,20 +22,21 @@ knitr::opts_chunk$set(
 [![codecov](https://codecov.io/github/msperlin/eodhd2/graph/badge.svg?token=9Y5GNHALC4)](https://codecov.io/github/msperlin/eodhd2)
 <!-- badges: end -->
 
-[eodhd](https://eodhd.com/) is a private company that offers access to a set of comprehensive and high quality financial data for over 70+ exchanges across the world. This includes:
+[eodhd](https://eodhd.com/) is a private company that offers APIs to a set of comprehensive and high quality financial data for over 70+ exchanges across the world. This includes:
 
 * Adjusted and unadjusted prices of financial contracts (equity, funds, ETF, cryptocurrencies, ..)
 * Financial information of companies (Balance Sheet, Income/Cashflow statement)
 * Valuation indicators
 * And [more](https://eodhd.com/)..
 
-Package eodhd2 is an R port of the API, allowing fast and intelligent access to most endpoints. 
+Package eodhd2 is the second and backwards incompatible version of [eodhd](https://github.com/EodHistoricalData/EODHD-APIs-R-Financial-Library), allowing fast and intelligent access to most of the API's endpoints. 
+
 
 # Features
 
-- A local caching system that saves queries to the disk, improving execution time and reducing api calls on repeated queries.
+- A local caching system that saves all API queries to the disk, improving execution time and reducing api calls on repeated queries.
 - A quota management system, informing the user of how much of the API daily quota was used and how much time is left to refresh it.
-- Function for aggregating and organizing financial information into a single dataframe, allowing easier access to clean financial data in the wide or long format.
+- Function for aggregating and organizing financial information into a single dataframe, allowing easier access to clean financial data in the [wide or long format](https://libguides.princeton.edu/R-reshape#:~:text=A%20dataset%20can%20be%20written,repeat%20in%20the%20first%20column.&text=We%20can%20see%20that%20in,value%20in%20the%20first%20column).
 
 
 # Installation
@@ -52,17 +53,20 @@ devtools::install_github("msperlin/eodhd2")
 
 ## Authentication
 
-After registering at the [website](https://eodhd.com/) and choosing a subscription, all users will authenticate an R session using a token from the website:
+After registering at the [website](https://eodhd.com/) and choosing a subscription, all users will authenticate an R session using a token from the website. For that:
+
+1) Create an account at [https://eodhd.com/](https://eodhd.com/)
+2) Go in "Settings" and look for your API token
 
 ![](inst/extdata/figs/token.png)
 
-The authentication is managed with function `set_token()`:
+While using `eodhd2`, all authentications are managed with function `eodhd2::set_token()`:
 
 ```{r, eval=FALSE}
 eodhd2::set_token("YOUR_TOKEN")
 ```
 
-Alternatively, you can use the "demo" token for demonstration.
+Alternatively, while testing the API, you can use the "demo" token for demonstration.
 
 ```{r, eval=TRUE}
 token <- eodhd2::get_demo_token()

diff --git a/README.md b/README.md
@@ -11,7 +11,7 @@
 [![codecov](https://codecov.io/github/msperlin/eodhd2/graph/badge.svg?token=9Y5GNHALC4)](https://codecov.io/github/msperlin/eodhd2)
 <!-- badges: end -->
 
-[eodhd](https://eodhd.com/) is a private company that offers access to a
+[eodhd](https://eodhd.com/) is a private company that offers APIs to a
 set of comprehensive and high quality financial data for over 70+
 exchanges across the world. This includes:
 
@@ -22,18 +22,20 @@ exchanges across the world. This includes:
 - Valuation indicators
 - And [more](https://eodhd.com/)..
 
-Package eodhd2 is an R port of the API, allowing fast and intelligent
-access to most endpoints.
+Package eodhd2 is the second and backwards incompatible version of
+[eodhd](https://github.com/EodHistoricalData/EODHD-APIs-R-Financial-Library),
+allowing fast and intelligent access to most of the API’s endpoints.
 
 # Features
 
-- A local caching system that saves queries to the disk, improving
-  execution time and reducing api calls on repeated queries.
+- A local caching system that saves all API queries to the disk,
+  improving execution time and reducing api calls on repeated queries.
 - A quota management system, informing the user of how much of the API
   daily quota was used and how much time is left to refresh it.
 - Function for aggregating and organizing financial information into a
   single dataframe, allowing easier access to clean financial data in
-  the wide or long format.
+  the [wide or long
+  format](https://libguides.princeton.edu/R-reshape#:~:text=A%20dataset%20can%20be%20written,repeat%20in%20the%20first%20column.&text=We%20can%20see%20that%20in,value%20in%20the%20first%20column).
 
 # Installation
 
@@ -51,27 +53,32 @@ devtools::install_github("msperlin/eodhd2")
 
 After registering at the [website](https://eodhd.com/) and choosing a
 subscription, all users will authenticate an R session using a token
-from the website:
+from the website. For that:
+
+1)  Create an account at <https://eodhd.com/>
+2)  Go in “Settings” and look for your API token
 
 ![](inst/extdata/figs/token.png)
 
-The authentication is managed with function `set_token()`:
+While using `eodhd2`, all authentications are managed with function
+`eodhd2::set_token()`:
 
 ``` r
 eodhd2::set_token("YOUR_TOKEN")
 ```
 
-Alternatively, you can use the “demo” token for demonstration.
+Alternatively, while testing the API, you can use the “demo” token for
+demonstration.
 
 ``` r
 token <- eodhd2::get_demo_token()
 eodhd2::set_token(token)
 #> ✔ eodhd API token set
 #> ℹ Account name: API Documentation 2 (supportlevel1@eodhistoricaldata.com)
-#> ℹ Quota: 46886 | 10000000
+#> ℹ Quota: 57033 | 10000000
 #> ℹ Subscription: demo
-#> ✖ You are using a DEMONSTRATION token for testing pourposes, with limited access to the data repositories.
-#> See <https://eodhd.com/> for registration and use function set_token(TOKEN) to set your own token.
+#> ✖ You are using a **DEMONSTRATION** token for testing pourposes, with limited access to the data repositories.
+#> See <https://eodhd.com/> for registration and, after finding your token, use it with function eodhd2::set_token(TOKEN).
 ```
 
 # Examples
@@ -84,9 +91,9 @@ exchange <- "US"
 
 df_prices <- eodhd2::get_prices(ticker, exchange)
 #> 
-#> ── fetching price data for ticker AAPL|US ──────────────────────────────────────
-#> ! Quota status: 46887|10000000, refreshing in 9.99 hours
-#> ℹ cache file '/tmp/RtmpT3AO3H/eodhd2-cache/AAPL_US_eodhd_prices.rds' saved
+#> ── retrieving price data for ticker AAPL|US ────────────────────────────────────
+#> ! Quota status: 57034|10000000, refreshing in 6.95 hours
+#> ℹ cache file '/tmp/RtmpjBU71O/eodhd2-cache/AAPL_US_eodhd_prices.rds' saved
 #> ✔    got 10959 rows of prices
 #> ℹ    got daily data from 1980-12-12 to 2024-06-03
 ```
@@ -134,9 +141,9 @@ exchange <- "US"
 
 df_div <- eodhd2::get_dividends(ticker, exchange)
 #> 
-#> ── fetching dividends for ticker AAPL|US ───────────────────────────────────────
-#> ! Quota status: 46890|10000000, refreshing in 9.99 hours
-#> ℹ cache file '/tmp/RtmpT3AO3H/eodhd2-cache/AAPL_US_eodhd_dividends.rds' saved
+#> ── retrieving dividends for ticker AAPL|US ─────────────────────────────────────
+#> ! Quota status: 57037|10000000, refreshing in 6.94 hours
+#> ℹ cache file '/tmp/RtmpjBU71O/eodhd2-cache/AAPL_US_eodhd_dividends.rds' saved
 #> ✔    got 83 rows of dividend data
 ```
 
@@ -182,8 +189,8 @@ exchange <- "US"
 
 l_fun <- eodhd2::get_fundamentals(ticker, exchange)
 #> 
-#> ── fetching fundamentals for ticker AAPL|US ────────────────────────────────────
-#> ! Quota status: 46891|10000000, refreshing in 9.99 hours
+#> ── retrieving fundamentals for ticker AAPL|US ──────────────────────────────────
+#> ! Quota status: 57038|10000000, refreshing in 6.94 hours
 #> ✔    querying API
 #> ✔    got 13 elements in raw list
 ```

diff --git a/tests/testthat/test-dividend.R b/tests/testthat/test-dividend.R
@@ -1,4 +1,4 @@
-test_that("fetch dividends", {
+test_that("dividends", {
 
   suppressMessages({
     set_token()

diff --git a/tests/testthat/test-prices.R b/tests/testthat/test-prices.R
@@ -1,4 +1,4 @@
-test_that("fetching prices", {
+test_that("prices", {
 
   suppressMessages({
     set_token()

diff --git a/tests/testthat/test-splits.R b/tests/testthat/test-splits.R
@@ -1,6 +1,5 @@
-test_that("fetching splits", {
+test_that("splits", {
 
-  #' Fetches dividend data from eodhd
   skip_if(get_token() == get_demo_token(),
           "Found a test/demo token, which does not allow for querying splits data")
 })