From 72240bf8b69388750b12383dcd4066caf4292648 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Ma=C3=ABlle=20Salmon?= <maelle.salmon@yahoo.se>
Date: Tue, 5 Nov 2024 16:00:16 +0100
Subject: [PATCH] docs: better manual pages for attributes related functions

---
 R/layer_attributes.R                | 24 ++++++++++++++----------
 man/layer_attribute_descriptions.Rd |  8 ++++++++
 man/layer_attribute_inspect.Rd      |  8 ++++++++
 man/layer_attributes_get_names.Rd   | 16 +++++++++++++---
 man/layer_attributes_summarise.Rd   | 10 +++++++++-
 man/layer_attributes_tbl.Rd         | 13 +++++++++++--
 6 files changed, 63 insertions(+), 16 deletions(-)

diff --git a/R/layer_attributes.R b/R/layer_attributes.R
index 45d8975..13973ee 100644
--- a/R/layer_attributes.R
+++ b/R/layer_attributes.R
@@ -7,15 +7,14 @@
 #'
 #' @return output of `summary()` on the attributes (variables) in a given layer
 #' for a given service.
+#' @family attributes
 #' @export
 #'
-#' @examples
-#' \dontrun{
+#' @examplesIf interactive
 #' layer_attributes_summarise(
 #'   service = "biology",
 #'   layer = "mediseh_zostera_m_pnt"
 #' )
-#' }
 layer_attributes_summarise <- function(wfs = NULL,
                                        service = NULL,
                                        service_version = NULL,
@@ -42,6 +41,7 @@ layer_attributes_summarise <- function(wfs = NULL,
 #' @inheritParams layer_attributes_summarise
 #'
 #' @return data.frame containing layer attribute descriptions (metadata).
+#' @family attributes
 #' @export
 #'
 #' @examplesIf interactive()
@@ -64,22 +64,23 @@ layer_attribute_descriptions <- function(wfs = NULL,
 }
 
 
-#' Get names of layer attributes
+#' Names of variables (attributes) available from a dataset (layer)
+#' in a data source (service).
 #'
 #' @inheritParams emodnet_init_wfs_client
 #' @inheritParams emodnet_get_wfs_info
 #' @inheritParams layer_attributes_summarise
 #'
+#' @family attributes
+#'
 #' @return character vector of layer attribute (variable) names.
 #' @export
 #'
-#' @examples
-#' \dontrun{
+#' @examplesIf interactive()
 #' layer_attributes_get_names(
 #'   service = "biology",
 #'   layer = "mediseh_zostera_m_pnt"
 #' )
-#' }
 layer_attributes_get_names <- function(wfs = NULL,
                                        service = NULL,
                                        service_version = NULL,
@@ -110,6 +111,7 @@ layer_attributes_get_names <- function(wfs = NULL,
 #' @return Detailed summary of individual attribute (variable). Particularly
 #' useful for inspecting
 #' factor or character variable levels or unique values.
+#' @family attributes
 #' @export
 #'
 #' @examplesIf interactive()
@@ -164,6 +166,9 @@ layer_attribute_inspect <- function(wfs = NULL,
 
 #' Get layer attribute values tibble
 #'
+#' Possible values of variables (attributes) in a dataset (layer)
+#' from a data source (service).
+#'
 #' @inheritParams emodnet_init_wfs_client
 #' @inheritParams emodnet_get_wfs_info
 #' @inheritParams layer_attributes_summarise
@@ -175,12 +180,11 @@ layer_attribute_inspect <- function(wfs = NULL,
 #' useful for inspecting attribute values and constructing feature filters
 #' for more
 #' targeted and faster layer download.
+#' @family attributes
 #' @export
 #'
-#' @examples
-#' \dontrun{
+#' @examplesIf interactive()
 #' layer_attributes_tbl(service = "biology", layer = "mediseh_zostera_m_pnt")
-#' }
 layer_attributes_tbl <- function(wfs = NULL,
                                  service = NULL,
                                  service_version = NULL, layer) {
diff --git a/man/layer_attribute_descriptions.Rd b/man/layer_attribute_descriptions.Rd
index 6bf30a2..344eb47 100644
--- a/man/layer_attribute_descriptions.Rd
+++ b/man/layer_attribute_descriptions.Rd
@@ -38,3 +38,11 @@ layer_attribute_descriptions(
 )
 \dontshow{\}) # examplesIf}
 }
+\seealso{
+Other attributes: 
+\code{\link{layer_attribute_inspect}()},
+\code{\link{layer_attributes_get_names}()},
+\code{\link{layer_attributes_summarise}()},
+\code{\link{layer_attributes_tbl}()}
+}
+\concept{attributes}
diff --git a/man/layer_attribute_inspect.Rd b/man/layer_attribute_inspect.Rd
index 6197714..63ec886 100644
--- a/man/layer_attribute_inspect.Rd
+++ b/man/layer_attribute_inspect.Rd
@@ -47,3 +47,11 @@ layer_attribute_inspect(
 )
 \dontshow{\}) # examplesIf}
 }
+\seealso{
+Other attributes: 
+\code{\link{layer_attribute_descriptions}()},
+\code{\link{layer_attributes_get_names}()},
+\code{\link{layer_attributes_summarise}()},
+\code{\link{layer_attributes_tbl}()}
+}
+\concept{attributes}
diff --git a/man/layer_attributes_get_names.Rd b/man/layer_attributes_get_names.Rd
index d136b72..3761579 100644
--- a/man/layer_attributes_get_names.Rd
+++ b/man/layer_attributes_get_names.Rd
@@ -2,7 +2,8 @@
 % Please edit documentation in R/layer_attributes.R
 \name{layer_attributes_get_names}
 \alias{layer_attributes_get_names}
-\title{Get names of layer attributes}
+\title{Names of variables (attributes) available from a dataset (layer)
+in a data source (service).}
 \usage{
 layer_attributes_get_names(
   wfs = NULL,
@@ -28,13 +29,22 @@ the WFS service version. Now always "2.0.0".}
 character vector of layer attribute (variable) names.
 }
 \description{
-Get names of layer attributes
+Names of variables (attributes) available from a dataset (layer)
+in a data source (service).
 }
 \examples{
-\dontrun{
+\dontshow{if (interactive()) (if (getRversion() >= "3.4") withAutoprint else force)(\{ # examplesIf}
 layer_attributes_get_names(
   service = "biology",
   layer = "mediseh_zostera_m_pnt"
 )
+\dontshow{\}) # examplesIf}
 }
+\seealso{
+Other attributes: 
+\code{\link{layer_attribute_descriptions}()},
+\code{\link{layer_attribute_inspect}()},
+\code{\link{layer_attributes_summarise}()},
+\code{\link{layer_attributes_tbl}()}
 }
+\concept{attributes}
diff --git a/man/layer_attributes_summarise.Rd b/man/layer_attributes_summarise.Rd
index 3dffeaf..08e701e 100644
--- a/man/layer_attributes_summarise.Rd
+++ b/man/layer_attributes_summarise.Rd
@@ -32,10 +32,18 @@ for a given service.
 Get summaries of layer attributes (variables)
 }
 \examples{
-\dontrun{
+\dontshow{if (interactive) (if (getRversion() >= "3.4") withAutoprint else force)(\{ # examplesIf}
 layer_attributes_summarise(
   service = "biology",
   layer = "mediseh_zostera_m_pnt"
 )
+\dontshow{\}) # examplesIf}
 }
+\seealso{
+Other attributes: 
+\code{\link{layer_attribute_descriptions}()},
+\code{\link{layer_attribute_inspect}()},
+\code{\link{layer_attributes_get_names}()},
+\code{\link{layer_attributes_tbl}()}
 }
+\concept{attributes}
diff --git a/man/layer_attributes_tbl.Rd b/man/layer_attributes_tbl.Rd
index 7981911..015ddd6 100644
--- a/man/layer_attributes_tbl.Rd
+++ b/man/layer_attributes_tbl.Rd
@@ -24,7 +24,8 @@ tibble of layer attribute (variable) values
 with geometry column removed.
 }
 \description{
-Get layer attribute values tibble
+Possible values of variables (attributes) in a dataset (layer)
+from a data source (service).
 }
 \details{
 Request excluding spatial information can be significantly faster.
@@ -34,7 +35,15 @@ for more
 targeted and faster layer download.
 }
 \examples{
-\dontrun{
+\dontshow{if (interactive()) (if (getRversion() >= "3.4") withAutoprint else force)(\{ # examplesIf}
 layer_attributes_tbl(service = "biology", layer = "mediseh_zostera_m_pnt")
+\dontshow{\}) # examplesIf}
 }
+\seealso{
+Other attributes: 
+\code{\link{layer_attribute_descriptions}()},
+\code{\link{layer_attribute_inspect}()},
+\code{\link{layer_attributes_get_names}()},
+\code{\link{layer_attributes_summarise}()}
 }
+\concept{attributes}