improve documentation for height() and area()

R/area.R

@@ -1,12 +1,16 @@
 # vim:textwidth=128:expandtab:shiftwidth=4:softtabstop=4
 
-#' Side-view Area of Mooring Element
+#' Get Mooring/Element side-view Area
 #'
-#' Returns the area of the mooring element, projected onto a vertical plane.
-#' This is computed using the `area` item stored within the element,
-#' adjusted for the angle, depending on the value of `phi`. Note that
-#' elements created by [float()] are assumed to be spherical, and so
-#' their orientation is not taken into account.
+#' `area` returns a numeric vector of mooring element side-view
+#' area(s), in square metres, taking into account the orientation of
+#' the element with respect to the vertical. (Floats are assumed to be
+#' spherical, so the orientation is irrelevant. This is not the case
+#' for wires and instruments.) The return value will be a single
+#' number if `m` is a single element but in a typical mooring it will
+#' have multiple values. The areas are listed with the top element
+#' first, i.e. in the reverse order to that used in constructing the
+#' mooring with [mooring()].
 #'
 #' When initially created, objects do not contain an angle value, but
 #' such values are inserted by [knockdown()]. Moorings that are
@@ -52,33 +56,21 @@
 #' @author Dan Kelley
 area <- function(m, phi = TRUE) {
     if (is.mooring(m)) {
-        # message("area case 1")
-        # print(areaFactor)
-        # print(sapply(m, \(mi) mi@area))
         sapply(m@elements, \(e) area(e, phi))
     } else if (is.mooringElement(m)) {
-        #message("DAN 1")
         if (is.float(m)) {
-            # message("DAN 2a")
-            #message("Dan 1")
             areaFactor <- 1.0
         } else {
-            # message("DAN 2b")
             if (is.logical(phi)) {
-                #message("DAN 3a")
                 if (phi) {
-                    #message("DAN 3a1")
                     areaFactor <- if (length(m@phi)) cos(m@phi) else 1 # FIXME: is this a good assumption?
                 } else {
-                    # message("DAN 3a2")
                     areaFactor <- 1.0
                 }
             } else {
-                # message("DAN 4")
                 areaFactor <- cos(phi)
             }
         }
-        # message("areaFactor=", areaFactor)
         areaFactor * m@area
     } else {
         stop("area can only be computed for a mooring or an individual element")

R/clamped.R

@@ -36,9 +36,11 @@
 #' # Notice that M is 40m long (the sum of the wire lengths)
 #' # but that m is longer, because the instrument height is
 #' # included.
-#' sum(sapply(m@elements, \(e) e@height)) # unclamped instrument
-#' sum(sapply(M@elements, \(e) e@height)) # clamped instrument
-#' i@height # instrument height
+## sum(sapply(m@elements, \(e) e@height)) # unclamped instrument
+#' sum(height(m))
+## sum(sapply(M@elements, \(e) e@height)) # clamped instrument
+#' sum(height(M))
+#' height(i)
 #'
 #' @export
 #'

R/height.R

@@ -1,16 +1,24 @@
 # vim:textwidth=128:expandtab:shiftwidth=4:softtabstop=4
 
-#' Get mooring/element height
+#' Get Mooring/Element Height
 #'
 #' @template meTemplate
 #'
-#' @return `height` returns a numeric vector of element(s) height, in m.  This will be
-#' a single value if the first element is a single element, or a longer vector if it
-#' is a mooring.
+#' @return `height` returns a numeric vector of mooring element height(s), in
+#' metres.  This will be a single value if `m` is a single element (as in
+#' the first Example) or a vector, for a typical mooring, which has
+#' multiple elements (as in the second Example). Note that, in the
+#' latter case, the heights are listed with the top element first,
+#' i.e. in the reverse order to that used in constructing the mooring
+#' with [mooring()].
 #'
 #' @examples
 #' library(mooring)
-#' height(float())
+#' # Example 1. height of an individual element
+#' height(float("HMB 20"))
+#'
+#' # Example 2. height of individual mooring elements, starting
+#' # with the float.
 #' m <- mooring(anchor(), wire(length = 100), float("HMB 20"), waterDepth = 120)
 #' height(m)
 #'
@@ -22,6 +30,7 @@ height <- function(m) {
         sapply(m@elements, \(e) e@height)
     } else if (is.mooringElement(m)) {
         m@height
-        #if (length(class(m)) == 2) m$height else stop("height can only be computed for a mooring or an element")
+    } else {
+        stop("height can only be computed for a mooring or an individual element")
     }
 }

docs/pkgdown.yml

@@ -8,5 +8,5 @@ articles:
   mooring: mooring.html
   object_orientation: object_orientation.html
   table_tennis: table_tennis.html
-last_built: 2024-06-07T19:20Z
+last_built: 2024-06-07T22:31Z