From 36073ae031176b1097c3ca79f370a15ee52f7b69 Mon Sep 17 00:00:00 2001
From: Dorchies David <david.dorchies@inrae.fr>
Date: Tue, 28 Dec 2021 11:12:05 +0100
Subject: [PATCH] docs: own page documentation for get_available_params

---
 R/doApiQuery.R              |  2 +-
 R/get_available_params.R    |  8 ++++++-
 man/doApiQuery.Rd           | 11 ++--------
 man/get_available_params.Rd | 43 +++++++++++++++++++++++++++++++++++++
 4 files changed, 53 insertions(+), 11 deletions(-)
 create mode 100644 man/get_available_params.Rd

diff --git a/R/doApiQuery.R b/R/doApiQuery.R
index 7915a56..4554201 100644
--- a/R/doApiQuery.R
+++ b/R/doApiQuery.R
@@ -22,7 +22,7 @@
 #' cfg <- config::get(file = system.file("config.yml", package = "hubeau"))
 #' names(cfg$apis)
 #'
-#' # To get the available operation in an API
+#' # To get the available endpoints in an API
 #' names(cfg$apis[["prelevements"]]$operations)
 #'
 #' # To get available parameters in operation "chroniques" of the API "prelevements"
diff --git a/R/get_available_params.R b/R/get_available_params.R
index 333e4f3..55a2a63 100644
--- a/R/get_available_params.R
+++ b/R/get_available_params.R
@@ -1,5 +1,11 @@
-#' @rdname doApiQuery
+#' List available query parameters of an API endpoint
+#'
+#' @inheritParams doApiQuery
+#'
+#' @return A [character] vector with available query parameters for the requested API/endpoint
+#'
 #' @export
+#' @inherit doApiQuery examples
 #'
 get_available_params <- function(api,
                                  operation,
diff --git a/man/doApiQuery.Rd b/man/doApiQuery.Rd
index cd0e8d2..fc26271 100644
--- a/man/doApiQuery.Rd
+++ b/man/doApiQuery.Rd
@@ -1,8 +1,7 @@
 % Generated by roxygen2: do not edit by hand
-% Please edit documentation in R/doApiQuery.R, R/get_available_params.R
+% Please edit documentation in R/doApiQuery.R
 \name{doApiQuery}
 \alias{doApiQuery}
-\alias{get_available_params}
 \title{Main internal functions for querying the Hub'eau APIs}
 \usage{
 doApiQuery(
@@ -11,12 +10,6 @@ doApiQuery(
   params,
   cfg = config::get(file = system.file("config.yml", package = "hubeau"))
 )
-
-get_available_params(
-  api,
-  operation,
-  cfg = config::get(file = system.file("config.yml", package = "hubeau"))
-)
 }
 \arguments{
 \item{api}{a \link{character} name of the API (e.g.: "indicateurs_services", "prelevements"...), see example for available APIs}
@@ -45,7 +38,7 @@ The functions \verb{get_[api]_[operation]} call the function \code{doQueryApi} a
 cfg <- config::get(file = system.file("config.yml", package = "hubeau"))
 names(cfg$apis)
 
-# To get the available operation in an API
+# To get the available endpoints in an API
 names(cfg$apis[["prelevements"]]$operations)
 
 # To get available parameters in operation "chroniques" of the API "prelevements"
diff --git a/man/get_available_params.Rd b/man/get_available_params.Rd
new file mode 100644
index 0000000..95040b2
--- /dev/null
+++ b/man/get_available_params.Rd
@@ -0,0 +1,43 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/get_available_params.R
+\name{get_available_params}
+\alias{get_available_params}
+\title{List available query parameters of an API endpoint}
+\usage{
+get_available_params(
+  api,
+  operation,
+  cfg = config::get(file = system.file("config.yml", package = "hubeau"))
+)
+}
+\arguments{
+\item{api}{a \link{character} name of the API (e.g.: "indicateurs_services", "prelevements"...), see example for available APIs}
+
+\item{operation}{a \link{character} name of the endpoint, see example for available endpoints in an API}
+
+\item{cfg}{a \link{config} object describing the configuration of the APIs. Use the internal package configuration by default
+configuration}
+}
+\value{
+A \link{character} vector with available query parameters for the requested API/endpoint
+}
+\description{
+List available query parameters of an API endpoint
+}
+\examples{
+# To get the available APIs in the package
+cfg <- config::get(file = system.file("config.yml", package = "hubeau"))
+names(cfg$apis)
+
+# To get the available endpoints in an API
+names(cfg$apis[["prelevements"]]$operations)
+
+# To get available parameters in operation "chroniques" of the API "prelevements"
+get_available_params(api = "prelevements", operation = "chroniques")
+
+# To query the operation "chroniques" of the API "prelevements"
+# on all devices in the commune of Romilly-sur-Seine in 2018
+doApiQuery(api = "prelevements",
+           operation = "chroniques",
+           params = list(code_commune_insee = "10323", annee = "2018"))
+}
-- 
GitLab