From ddc5b5b4f82964fdd9cdb45674102e3fb012dfd7 Mon Sep 17 00:00:00 2001
From: Tini Garske <t.garske@imperial.ac.uk>
Date: Thu, 8 Feb 2024 12:48:56 +0000
Subject: [PATCH] update documentation for vip_pop_from_file()

---
 R/vip_population.R       | 17 ++++++++++-------
 man/vip_pop_from_file.Rd |  6 ++++--
 man/vip_population.Rd    |  4 ++--
 3 files changed, 16 insertions(+), 11 deletions(-)

diff --git a/R/vip_population.R b/R/vip_population.R
index 969307b..11d8667 100644
--- a/R/vip_population.R
+++ b/R/vip_population.R
@@ -17,9 +17,9 @@
 ##' @param year_min integer, first year to be considered.
 ##' @param year_max integer, last year to be considered.
 ##' @param age_min integer, youngest age to be considered, defaults to
-##'     0.
+##'     0. Must be non-negative.
 ##' @param age_max integer, oldest age to be considered, defaults to
-##'     100.
+##'     100. Must be non-negative, and >= age_min.
 ##' @return S3 object of class "vip_population": a dataframe with
 ##'     columns region, year, age, cohort, immunity and pop_size,
 ##'     where year and age cover the ranges given by the input
@@ -95,10 +95,12 @@ vip_population <- function(region = character(),
 ##' @param file Name of the .csv file from which the population data
 ##'     are to be read. If it does not contain an absolute path, the
 ##'     file name is relative to the current working directory.
-##' @return object of class "vip_population", a dataframe with one row
+##' @return An object of class "vip_population", a dataframe with one row
 ##'     per birth cohort/year/region, with columns "region", "year",
 ##'     "age", "cohort", "immunity", "pop_size".
-##' @seealso [utils::read.csv()] which handles the reading of the .csv file.
+##' @seealso [vip_population()] for details of the S3 class, and
+##'     [utils::read.csv()] which handles the reading of the .csv
+##'     file.
 ##' @author Tini Garske
 ##' @export
 vip_pop_from_file <- function(file) {
@@ -113,10 +115,11 @@ vip_pop_from_file <- function(file) {
     pop
 }
 
-##' Convert a dataframe to a vip_population object
+##' Generate a "vip_population" object from a dataframe
 ##'
-##' `convert_df_to_pop` converts a suitable dataframe to a vip
-##' population object and returns this object.
+##' Checks if the dataframe is suitable (i.e., contains appropriate
+##' columns and data ranges), and if so converts it to a
+##' "vip_population" object and returns this.
 ##'
 ##' The input dataframe has to have at least the columns region, age,
 ##' and year. The output vip_population object is generated via
diff --git a/man/vip_pop_from_file.Rd b/man/vip_pop_from_file.Rd
index cd1ead6..c6773be 100644
--- a/man/vip_pop_from_file.Rd
+++ b/man/vip_pop_from_file.Rd
@@ -12,7 +12,7 @@ are to be read. If it does not contain an absolute path, the
 file name is relative to the current working directory.}
 }
 \value{
-object of class "vip_population", a dataframe with one row
+An object of class "vip_population", a dataframe with one row
 per birth cohort/year/region, with columns "region", "year",
 "age", "cohort", "immunity", "pop_size".
 }
@@ -36,7 +36,9 @@ Limitations for values:
 }
 }
 \seealso{
-\code{\link[utils:read.table]{utils::read.csv()}} which handles the reading of the .csv file.
+\code{\link[=vip_population]{vip_population()}} for details of the S3 class, and
+\code{\link[utils:read.table]{utils::read.csv()}} which handles the reading of the .csv
+file.
 }
 \author{
 Tini Garske
diff --git a/man/vip_population.Rd b/man/vip_population.Rd
index d297a10..e3d0172 100644
--- a/man/vip_population.Rd
+++ b/man/vip_population.Rd
@@ -20,10 +20,10 @@ vip_population(
 \item{year_max}{integer, last year to be considered.}
 
 \item{age_min}{integer, youngest age to be considered, defaults to
-0.}
+0. Must be non-negative.}
 
 \item{age_max}{integer, oldest age to be considered, defaults to
-100.}
+100. Must be non-negative, and >= age_min.}
 }
 \value{
 S3 object of class "vip_population": a dataframe with