From 2738046fa169ed04250ea74639f3139440d66c91 Mon Sep 17 00:00:00 2001
From: Robin Lovelace <rob00x@gmail.com>
Date: Mon, 9 Nov 2020 21:15:47 +0000
Subject: [PATCH] Document slope_vector() functions

---
 DESCRIPTION         |  4 +++-
 R/slopes.R          | 21 ++++++++++++++++-----
 man/slope_vector.Rd | 19 +++++++++++++++----
 3 files changed, 34 insertions(+), 10 deletions(-)

diff --git a/DESCRIPTION b/DESCRIPTION
index ded3cf4..d4ff43e 100644
--- a/DESCRIPTION
+++ b/DESCRIPTION
@@ -41,5 +41,7 @@ Suggests:
     rmarkdown,
     ceramic,
     bookdown,
-    covr
+    covr,
+    testthat
 VignetteBuilder: knitr
+Config/testthat/edition: 3
diff --git a/R/slopes.R b/R/slopes.R
index b433d8d..fe4066e 100644
--- a/R/slopes.R
+++ b/R/slopes.R
@@ -1,5 +1,17 @@
 #' Calculate the gradient of line segments from distance and elevation vectors
 #'
+#' [slope_vector()] calculates the slopes associated with consecutive elements in one dimensional distance
+#' and associated elevations (see examples).
+#'
+#' [slope_distance()] calculates the slopes associated with consecutive distances and elevations.
+#'
+#' [slope_distance_mean()] calculates the mean average slopes associated with consecutive distances and elevations.
+#'
+#' [slope_distance_weighted()] calculates the slopes associated with consecutive distances and elevations,
+#' with the mean value associated with each set of distance/elevation vectors weighted in
+#' proportion to the distance between each elevation measurement, so longer sections
+#' have proportionally more influence on the resulting gradient estimate (see examples).
+#'
 #' @param x Vector of locations
 #' @param d Vector of distances between points
 #' @param e Elevations in same units as x (assumed to be metres)
@@ -27,17 +39,16 @@ slope_distance = function(d, e) {
 }
 #' @rdname slope_vector
 #' @export
-slope_distance_weighted = function(d, e) {
+slope_distance_mean = function(d, e) {
   e_change = diff(e)
-  stats::weighted.mean(abs(e_change) / d, d)
+  mean(abs(e_change) / d)
 }
 #' @rdname slope_vector
 #' @export
-slope_distance_mean = function(d, e) {
+slope_distance_weighted = function(d, e) {
   e_change = diff(e)
-  mean(abs(e_change) / d)
+  stats::weighted.mean(abs(e_change) / d, d)
 }
-
 #' Calculate the gradient of line segments from a 3D matrix of coordinates
 #'
 #' @param m Matrix containing coordinates and elevations
diff --git a/man/slope_vector.Rd b/man/slope_vector.Rd
index 2a97897..cd0848a 100644
--- a/man/slope_vector.Rd
+++ b/man/slope_vector.Rd
@@ -3,17 +3,17 @@
 \name{slope_vector}
 \alias{slope_vector}
 \alias{slope_distance}
-\alias{slope_distance_weighted}
 \alias{slope_distance_mean}
+\alias{slope_distance_weighted}
 \title{Calculate the gradient of line segments from distance and elevation vectors}
 \usage{
 slope_vector(x, e)
 
 slope_distance(d, e)
 
-slope_distance_weighted(d, e)
-
 slope_distance_mean(d, e)
+
+slope_distance_weighted(d, e)
 }
 \arguments{
 \item{x}{Vector of locations}
@@ -23,7 +23,18 @@ slope_distance_mean(d, e)
 \item{d}{Vector of distances between points}
 }
 \description{
-Calculate the gradient of line segments from distance and elevation vectors
+\code{\link[=slope_vector]{slope_vector()}} calculates the slopes associated with consecutive elements in one dimensional distance
+and associated elevations (see examples).
+}
+\details{
+\code{\link[=slope_distance]{slope_distance()}} calculates the slopes associated with consecutive distances and elevations.
+
+\code{\link[=slope_distance_mean]{slope_distance_mean()}} calculates the mean average slopes associated with consecutive distances and elevations.
+
+\code{\link[=slope_distance_weighted]{slope_distance_weighted()}} calculates the slopes associated with consecutive distances and elevations,
+with the mean value associated with each set of distance/elevation vectors weighted in
+proportion to the distance between each elevation measurement, so longer sections
+have proportionally more influence on the resulting gradient estimate (see examples).
 }
 \examples{
 x = c(0, 2, 3, 4, 5, 9)