---
title: "Design Principles for authoritative"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Design Principles for authoritative}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r}
#| include: false
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

This vignette outlines the design decisions that have been taken during the development of the `{authoritative}` R package, and provides some of the reasoning, and possible pros and cons of each decision.

This document is primarily intended to be read by those interested in understanding the code within the package and for potential package contributors.

<!-- Text in angular brackets (<>) is to guide what to include for each section please delete the guidelines and replace for your package.

None of the sections are required, feel free to remove any sections not relevant to your package or add new sections if helpful. -->

## Scope

This package has two main functionalities:

- the first is relevant to the ecosystem of R package and its analysis. It provides functions to parse and extract information from the `Author` and `Authors@R` fields from `DESCRIPTION`
- the second is more widely relevant, beyond the specific case of R package authors. It provides general purpose functions to deduplicate and standardize author names.

## Naming conventions

- Functions for deduplication are named `<verb>_names()`.

## Input/Output/Interoperability

- Functions for deduplication:
  - take a messy vector of names as first argument
  - take a source of truth vector of names as second argument
  - return a cleaned vector of names of the same length as the first argument

## Design decisions

## Dependencies

This package imports stringi as a dependency. Most of the operations performed by the package are string manipulations, and stringi increases performance and readability of the code compared to base R functions.