#' Function title (one line, sentence case)
#'
#' Longer description paragraph providing more details about what
#' the function does, when to use it, and any important context.
#'
#' @param x Description of parameter x
#' @param y Description of parameter y
#' @returns Description of return value
#' @export
#' @examples
#' my_function(1, 2)
my_function <- function(x, y) {
  # implementation
}

# Generate .Rd files and NAMESPACE:
devtools::document()

# Or:
roxygen2::roxygenise()

# Preview documentation:
?my_function

#' @param x A numeric vector of values
#' @param y A numeric vector, same length as x
#' @param method Character string specifying the method to use.
#'   Options are "mean" (default), "median", or "mode".
#' @param verbose Logical. If TRUE, prints progress messages.
#'   Default is FALSE.
#' @param ... Additional arguments passed to underlying functions

#' @returns A numeric vector of the same length as the input
my_function <- function(x) {
  x * 2
}

#' @returns A data frame with columns:
#'   \describe{
#'     \item{id}{Character. Unique identifier}
#'     \item{value}{Numeric. Measured value}
#'     \item{timestamp}{POSIXct. Time of measurement}
#'   }
my_summarize <- function(data) {
  # ...
}

#' @returns Invisible NULL. Called for side effects (prints plot).
my_plot <- function(x) {
  plot(x)
  invisible(NULL)
}

#' @returns A list with components:
#'   * `estimate`: Numeric vector of estimates
#'   * `std_error`: Standard errors
#'   * `p_value`: P-values
my_test <- function(x, y) {
  list(
    estimate = c(1, 2),
    std_error = c(0.1, 0.2),
    p_value = c(0.01, 0.05)
  )
}

#' User-facing function
#' @export
public_function <- function() {
  # ...
}

#' Internal function (no @export)
internal_helper <- function() {
  # ...
}

#' @examples
#' # Basic usage
#' result <- my_function(1:10)
#'
#' # With different parameters
#' result2 <- my_function(1:10, method = "median")
#'
#' # Handling edge cases
#' my_function(numeric(0))  # Empty input
my_function <- function(x, method = "mean") {
  # ...
}

#' @examplesIf requireNamespace("ggplot2", quietly = TRUE)
#' library(ggplot2)
#' ggplot(data, aes(x, y)) + geom_point()

#' @examplesIf interactive()
#' # Only run in interactive sessions
#' my_interactive_function()

#' @examplesIf identical(Sys.getenv("NOT_CRAN"), "true")
#' # Only on GitHub Actions, not CRAN
#' slow_test()

#' @examples
#' # This runs:
#' my_function(1:10)
#'
#' \dontrun{
#' # This is shown but NEVER run (not even by check):
#' # Use for code that requires user interaction or credentials
#' my_function(get_user_input())
#' set_api_key("your-key-here")
#' }
#'
#' \donttest{
#' # This is run by check, but not by example():
#' # Use for slow operations
#' very_slow_operation()
#' }

#' @importFrom dplyr filter mutate select
#' @importFrom rlang .data %||%
#' @importFrom stats median sd
NULL

# R/aaa-imports.R
#' @importFrom dplyr filter mutate select arrange
#' @importFrom rlang .data .env %||% !! !!!
#' @importFrom magrittr %>%
NULL

#' @import rlang
NULL

#' Internal helper function
#'
#' This function is not intended for direct use.
#'
#' @keywords internal
#' @export
internal_but_exported <- function() {
  # Sometimes needed for S3 methods, package architecture
}

#' Base function
#' @param x A numeric vector
#' @param y A numeric vector
#' @param method Method to use: "mean", "median", or "mode"
base_function <- function(x, y, method = "mean") {
  # ...
}

#' Wrapper function
#' @inheritParams base_function
#' @param z Additional parameter
wrapper_function <- function(x, y, method = "mean", z) {
  base_function(x, y, method)
  # ... use z ...
}

#' Original function
#' @param x Input
#' @returns Output
#' @examples
#' original(1:10)
original <- function(x) {
  # ...
}

#' @inherit original examples
#' @inheritParams original
#' @returns Modified output
modified <- function(x) {
  # different implementation
}

#' @family statistical functions
mean_wrapper <- function(x) {
  mean(x)
}

#' @family statistical functions
median_wrapper <- function(x) {
  median(x)
}

#' @family statistical functions
mode_wrapper <- function(x) {
  # ...
}

#' @seealso [related_function()] for related functionality
#' @seealso [other_package::their_function()] for alternative approach
#' @seealso <https://example.com> for more details
#' @seealso `vignette("introduction")` for tutorial

#' Get or set configuration
#'
#' @param key Configuration key
#' @param value Configuration value
#' @rdname config
#' @export
get_config <- function(key) {
  pkg_env$config[[key]]
}

#' @rdname config
#' @export
set_config <- function(key, value) {
  pkg_env$config[[key]] <- value
  invisible(value)
}

#' Process data
#'
#' @param x Input data
#' @export
process <- function(x) {
  UseMethod("process")
}

#' @describeIn process Process numeric vectors
#' @export
process.numeric <- function(x) {
  # ...
}

#' @describeIn process Process character vectors
#' @export
process.character <- function(x) {
  # ...
}

#' @describeIn process Process data frames
#' @export
process.data.frame <- function(x) {
  # ...
}

Roxygen: list(markdown = TRUE)

#' Function with *italic*, **bold**, and `code` text
#'
#' You can use _italic_ and __bold__ alternatives too.
#'
#' Inline code: `x + y`
#'
#' Code blocks:
#' ```
#' result <- my_function(
#'   x = 1:10,
#'   method = "mean"
#' )
#' ```

#' Bulleted list:
#' * Item 1
#' * Item 2
#'   * Nested item
#' * Item 3
#'
#' Numbered list:
#' 1. First step
#' 2. Second step
#' 3. Third step
#'
#' Definition list:
#' * `term1`: Definition of term 1
#' * `term2`: Definition of term 2

#' See [my_function()] for details
#'
#' See [other_package::their_function()] for alternatives
#'
#' See [my_function()] and [another_function()] for related work
#'
#' See the vignette: `vignette("introduction", package = "mypackage")`
#'
#' External link: <https://example.com>
#' Or: [Link text](https://example.com)

#' # Major section
#'
#' Content here
#'
#' ## Subsection
#'
#' More content
#'
#' ### Sub-subsection
#'
#' Even more content

#' World Health Organization TB data
#'
#' A subset of data from the World Health Organization Global Tuberculosis
#' Report containing tuberculosis cases by country, year, age, and sex.
#'
#' @format A data frame with 7,240 rows and 60 columns:
#' \describe{
#'   \item{country}{Character. Country name}
#'   \item{iso2}{Character. 2-letter ISO country code}
#'   \item{iso3}{Character. 3-letter ISO country code}
#'   \item{year}{Integer. Year of observation (1995-2013)}
#'   \item{new_sp_m014}{Integer. New smear-positive cases, males aged 0-14}
#'   \item{new_sp_f014}{Integer. New smear-positive cases, females aged 0-14}
#' }
#'
#' @source World Health Organization Global Tuberculosis Report
#'   \url{https://www.who.int/teams/global-tuberculosis-programme/data}
#'
#' @examples
#' head(who)
#' summary(who$year)
"who"

#' Example vector
#'
#' @format A numeric vector of length 100
"example_vector"

#' Example list
#'
#' @format A list with components:
#' \describe{
#'   \item{x}{Numeric vector}
#'   \item{y}{Character vector}
#'   \item{metadata}{List of metadata}
#' }
"example_list"

#' Example matrix
#'
#' @format A 10x10 numeric matrix
"example_matrix"

# R/mypackage-package.R

#' mypackage: Brief Package Description
#'
#' A longer description of what the package does. This should be
#' one paragraph providing enough detail for users to understand
#' the package's purpose and scope.
#'
#' @section Main functions:
#' * [important_function()] - does important things
#' * [another_function()] - does other things
#' * [helper_function()] - helps with things
#'
#' @section Getting started:
#' See `vignette("introduction")` for a tutorial.
#'
#' @keywords internal
#' @importFrom rlang .data %||%
#' @importFrom dplyr filter mutate select
"_PACKAGE"

#' Print method for myclass objects
#'
#' @param x A myclass object
#' @param ... Additional arguments (ignored)
#' @returns Invisible x (called for side effects)
#' @export
print.myclass <- function(x, ...) {
  cat("myclass object with", length(x), "elements\n")
  invisible(x)
}

#' Summary method for myclass objects
#'
#' @inheritParams print.myclass
#' @returns A summary_myclass object
#' @export
summary.myclass <- function(x, ...) {
  structure(
    list(n = length(x), mean = mean(x)),
    class = "summary_myclass"
  )
}

#' Arithmetic operations
#'
#' Basic arithmetic operations for custom objects.
#'
#' @param x,y Numeric vectors
#' @name arithmetic
#' @returns Numeric vector
NULL

#' @rdname arithmetic
#' @export
add <- function(x, y) x + y

#' @rdname arithmetic
#' @export
subtract <- function(x, y) x - y

#' @rdname arithmetic
#' @export
multiply <- function(x, y) x * y

#' @rdname arithmetic
#' @export
divide <- function(x, y) x / y

# man-roxygen/common-params.R (not R/ directory!)
#' @param verbose Logical. If TRUE, prints progress messages.
#' @param ... Additional arguments passed to underlying functions.

# Then in function documentation:
#' My function
#' @template common-params
#' @export
my_function <- function(verbose = FALSE, ...) {
  # ...
}

#' Brief title (one line, sentence case)
#'
#' Longer description providing context and details about when to use
#' this function and what it does.
#'
#' @param x A numeric vector. Input values to process.
#' @param method Character string specifying method. Options:
#'   * "mean" (default) - arithmetic mean
#'   * "median" - median value
#'   * "mode" - most common value
#' @param na.rm Logical. Should missing values be removed? Default is FALSE.
#' @param verbose Logical. Print progress messages? Default is FALSE.
#' @param ... Additional arguments passed to underlying functions.
#'
#' @returns A numeric vector of the same length as `x`.
#'
#' @export
#' @examples
#' # Basic usage
#' my_function(1:10)
#'
#' # With different method
#' my_function(1:10, method = "median")
#'
#' # Handling missing values
#' my_function(c(1, NA, 3), na.rm = TRUE)
#'
#' @seealso [related_function()] for related functionality
#' @family processing functions
my_function <- function(x, method = "mean", na.rm = FALSE,
                        verbose = FALSE, ...) {
  # implementation
}

#' Internal helper function
#'
#' This function is not intended for direct use by package users.
#' It provides internal utilities for other package functions.
#'
#' @param x Input data
#' @returns Processed data
#' @keywords internal
#' @noRd
internal_helper <- function(x) {
  # implementation
}

#' Example dataset for demonstrations
#'
#' A synthetic dataset containing measurements of various properties
#' across different conditions. Useful for testing and examples.
#'
#' @format A data frame with 150 rows and 5 columns:
#' \describe{
#'   \item{id}{Character. Unique identifier for each observation}
#'   \item{value}{Numeric. Measured value (range: 0-100)}
#'   \item{category}{Factor. Category label (A, B, or C)}
#'   \item{timestamp}{POSIXct. Time of measurement}
#'   \item{valid}{Logical. Whether measurement passed quality checks}
#' }
#'
#' @source Generated synthetically for package examples
#'
#' @examples
#' head(example_data)
#' summary(example_data)
#'
#' # Basic analysis
#' mean(example_data$value)
#' table(example_data$category)
"example_data"

#' mypackage: Tools for Data Analysis
#'
#' mypackage provides a set of tools for common data analysis tasks,
#' including data cleaning, transformation, and visualization. It is
#' designed to work seamlessly with the tidyverse ecosystem.
#'
#' @section Main functions:
#' Data processing:
#' * [clean_data()] - clean and validate data
#' * [transform_data()] - apply transformations
#'
#' Analysis:
#' * [analyze_data()] - perform statistical analysis
#' * [summarize_results()] - summarize analysis results
#'
#' Visualization:
#' * [plot_data()] - create data visualizations
#'
#' @section Getting started:
#' See `vignette("introduction")` for a comprehensive tutorial.
#'
#' @keywords internal
#' @importFrom rlang .data .env %||% !! !!!
#' @importFrom dplyr filter mutate select arrange
#' @import ggplot2
"_PACKAGE"

# WRONG:
#' Function title
#' More description
#' @param x Input

# RIGHT:
#' Function title
#'
#' More description
#'
#' @param x Input

# OLD:
#' @return A numeric vector

# NEW:
#' @returns A numeric vector

# Function is internal (not exported):
#' Public-facing function
my_function <- function() {}

# Need to export:
#' Public-facing function
#' @export
my_function <- function() {}

# WARNING - y not documented:
#' @param x Input
my_function <- function(x, y) {}

# CORRECT:
#' @param x Input
#' @param y Other input
my_function <- function(x, y) {}

# WRONG - no parentheses, no link created:
#' See my_function for details

# RIGHT:
#' See [my_function()] for details

# INCOMPLETE:
#' My dataset
"dataset"

# COMPLETE:
#' My dataset
#' @format A data frame with 100 rows and 5 columns
"dataset"

# OLD (without Markdown):
#' \code{x} is a vector

# NEW (with Markdown):
#' `x` is a vector

# WRONG - example will fail:
#' @examples
#' my_function(nonexistent_object)

# RIGHT:
#' @examples
#' my_function(1:10)

# Exported but internal (e.g., S3 method):
#' @export
#' @keywords internal
internal_but_exported <- function() {}

# After changing roxygen comments:
devtools::document()

# Or:
roxygen2::roxygenise()

#' @param name Description
#' @returns What the function returns
#' @export
#' @examples code
#' @importFrom pkg fun
#' @import pkg
#' @keywords internal
#' @seealso [other_function()]
#' @family function_family
#' @inheritParams other_function
#' @inherit other_function return examples
#' @rdname combined_topic
#' @describeIn generic_function Method description

#' *italic* or _italic_
#' **bold** or __bold__
#' `code`
#' [function_name()] - auto-link
#' [pkg::function()] - cross-package link
#' <https://example.com> - URL
#' * Bullet point
#' 1. Numbered item