From 5fed2bfcd17401732312a85291a10cb8bf6ec6f1 Mon Sep 17 00:00:00 2001
From: AlbanSagouis <sagouis@pm.me>
Date: Mon, 16 Mar 2026 12:05:35 +0100
Subject: [PATCH 1/4] CRAN submission

---
 .Rbuildignore | 1 +
 DESCRIPTION   | 4 +++-
 codemeta.json | 4 +++-
 3 files changed, 7 insertions(+), 2 deletions(-)

diff --git a/.Rbuildignore b/.Rbuildignore
index ecd06c4..dda5f2b 100644
--- a/.Rbuildignore
+++ b/.Rbuildignore
@@ -8,3 +8,4 @@
 ^synced_episode.srt/
 ^cran-comments\.md$
 ^codemeta\.json$
+^CRAN-SUBMISSION$
diff --git a/DESCRIPTION b/DESCRIPTION
index 01497b0..fbadd6f 100644
--- a/DESCRIPTION
+++ b/DESCRIPTION
@@ -2,7 +2,7 @@ Package: subtools
 Type: Package
 Title: Read and Manipulate Video Subtitles
 Version: 1.1.0
-Date: 2026-03-11
+Date: 2026-03-16
 Authors@R: c(
       person("Francois", "Keck", email = "francois.keck@gmail.com",
              role =  c("aut", "cre", "cph"),
@@ -40,3 +40,5 @@ Config/testthat/edition: 3
 Config/testthat/parallel: false
 Config/testthat/start-first: *assert*, *utils*, *read*
 RoxygenNote: 7.3.3
+X-schema.org-applicationCategory: Text Processing
+X-schema.org-keywords: subtitles, video, text, srt, vtt, ssa, natural language processing
diff --git a/codemeta.json b/codemeta.json
index c325cc1..69b5cc4 100644
--- a/codemeta.json
+++ b/codemeta.json
@@ -203,7 +203,9 @@
     },
     "SystemRequirements": null
   },
-  "fileSize": "169.162KB",
+  "applicationCategory": "TextProcessing",
+  "keywords": ["subtitles", "video", "text", "srt", "vtt", "ssa", "naturallanguageprocessing"],
+  "fileSize": "183.692KB",
   "codeRepository": "https://github.com/fkeck/subtools",
   "releaseNotes": "https://github.com/fkeck/subtools/blob/master/NEWS.md",
   "readme": "https://github.com/fkeck/subtools/blob/main/README.md",

From 9726f0e2ed1b5564505d8570333423ca4211ee07 Mon Sep 17 00:00:00 2001
From: AlbanSagouis <sagouis@pm.me>
Date: Tue, 17 Mar 2026 11:12:12 +0100
Subject: [PATCH 2/4] CRAN submission

---
 .Rbuildignore    |  1 +
 README.md        | 44 ++++++++++++++++++++++----------------------
 codemeta.json    |  2 +-
 tests/testthat.R |  1 -
 4 files changed, 24 insertions(+), 24 deletions(-)

diff --git a/.Rbuildignore b/.Rbuildignore
index dda5f2b..075363e 100644
--- a/.Rbuildignore
+++ b/.Rbuildignore
@@ -9,3 +9,4 @@
 ^cran-comments\.md$
 ^codemeta\.json$
 ^CRAN-SUBMISSION$
+^tests.R$
diff --git a/README.md b/README.md
index 4680e0a..3e214c3 100644
--- a/README.md
+++ b/README.md
@@ -55,8 +55,8 @@ oss_sub <- read_subtitles("ex_OSS_117.srt")
 ``` r
 rushmore_sub
 #> # A tibble: 4 × 4
-#>   ID    Timecode_in Timecode_out Text_content                                   
-#>   <chr> <time>      <time>       <chr>                                          
+#>   ID    Timecode_in Timecode_out Text_content
+#>   <chr> <time>      <time>       <chr>
 #> 1 180   20'40.969"  20'48.269"   Rushmore deserves an aquarium. A first class a…
 #> 2 181   20'48.269"  20'50.870"   - I don't know. What do you think, Ernie - Aqu…
 #> 3 182   20'50.946"  20'57.370"   - What kind of fish? - Barracudas. Stingrays. …
@@ -64,10 +64,10 @@ rushmore_sub
 
 oss_sub
 #> # A tibble: 3 × 4
-#>   ID    Timecode_in Timecode_out Text_content                                   
-#>   <chr> <time>      <time>       <chr>                                          
+#>   ID    Timecode_in Timecode_out Text_content
+#>   <chr> <time>      <time>       <chr>
 #> 1 264   20'22.967"  20'27.427"   Si vous voulez. Ça sera surtout l'occasion de …
-#> 2 265   20'30.347"  20'32.297"   Et non pas le gratin de pommes de terre.       
+#> 2 265   20'30.347"  20'32.297"   Et non pas le gratin de pommes de terre.
 #> 3 266   20'35.587"  20'37.697"   Parce que ça ressemble à carotte, cairote.
 ```
 
@@ -184,14 +184,14 @@ multi_sub
 #> A multisubtitles object with 2 elements
 #> subtitles object [[1]]
 #> # A tibble: 4 × 4
-#>   ID    Timecode_in Timecode_out Text_content                                   
-#>   <chr> <time>      <time>       <chr>                                          
+#>   ID    Timecode_in Timecode_out Text_content
+#>   <chr> <time>      <time>       <chr>
 #> 1 180   20'40.969"  20'48.269"   Rushmore deserves an aquarium. A first class a…
 #> 2 181   20'48.269"  20'50.870"   - I don't know. What do you think, Ernie - Aqu…
 #> 3 182   20'50.946"  20'57.370"   - What kind of fish? - Barracudas. Stingrays. …
 #> 4 183   20'58.051"  21'01.770"   - Piranhas? Really? - Yes, I'm talking to a gu…
-#> 
-#> 
+#>
+#>
 #> subtitles object [[2]]
 #> # A tibble: 4 × 7
 #>   ID    Timecode_in Timecode_out Text_content               Name  Season Episode
@@ -232,8 +232,8 @@ timecode remapping according to the tokenisation process.
 ``` r
 rushmore_sub
 #> # A tibble: 4 × 4
-#>   ID    Timecode_in Timecode_out Text_content                                   
-#>   <chr> <time>      <time>       <chr>                                          
+#>   ID    Timecode_in Timecode_out Text_content
+#>   <chr> <time>      <time>       <chr>
 #> 1 180   20'40.969"  20'48.269"   Rushmore deserves an aquarium. A first class a…
 #> 2 181   20'48.269"  20'50.870"   - I don't know. What do you think, Ernie - Aqu…
 #> 3 182   20'50.946"  20'57.370"   - What kind of fish? - Barracudas. Stingrays. …
@@ -242,17 +242,17 @@ rushmore_sub
 unnest_tokens(rushmore_sub)
 #> # A tibble: 49 × 4
 #>    ID    Timecode_in Timecode_out Text_content
-#>    <chr> <time>      <time>       <chr>       
-#>  1 180   20'40.9700" 20'41.4858"  rushmore    
-#>  2 180   20'41.4868" 20'42.0026"  deserves    
-#>  3 180   20'42.0036" 20'42.1318"  an          
-#>  4 180   20'42.1328" 20'42.6486"  aquarium    
-#>  5 180   20'42.6496" 20'42.7132"  a           
-#>  6 180   20'42.7142" 20'43.0363"  first       
-#>  7 180   20'43.0373" 20'43.3593"  class       
-#>  8 180   20'43.3603" 20'43.8761"  aquarium    
-#>  9 180   20'43.8771" 20'44.1991"  where       
-#> 10 180   20'44.2001" 20'44.8451"  scientists  
+#>    <chr> <time>      <time>       <chr>
+#>  1 180   20'40.9700" 20'41.4858"  rushmore
+#>  2 180   20'41.4868" 20'42.0026"  deserves
+#>  3 180   20'42.0036" 20'42.1318"  an
+#>  4 180   20'42.1328" 20'42.6486"  aquarium
+#>  5 180   20'42.6496" 20'42.7132"  a
+#>  6 180   20'42.7142" 20'43.0363"  first
+#>  7 180   20'43.0373" 20'43.3593"  class
+#>  8 180   20'43.3603" 20'43.8761"  aquarium
+#>  9 180   20'43.8771" 20'44.1991"  where
+#> 10 180   20'44.2001" 20'44.8451"  scientists
 #> # ℹ 39 more rows
 
 unnest_tokens(bb_sub_clean, token = "sentences")
diff --git a/codemeta.json b/codemeta.json
index 69b5cc4..c669143 100644
--- a/codemeta.json
+++ b/codemeta.json
@@ -205,7 +205,7 @@
   },
   "applicationCategory": "TextProcessing",
   "keywords": ["subtitles", "video", "text", "srt", "vtt", "ssa", "naturallanguageprocessing"],
-  "fileSize": "183.692KB",
+  "fileSize": "183.292KB",
   "codeRepository": "https://github.com/fkeck/subtools",
   "releaseNotes": "https://github.com/fkeck/subtools/blob/master/NEWS.md",
   "readme": "https://github.com/fkeck/subtools/blob/main/README.md",
diff --git a/tests/testthat.R b/tests/testthat.R
index ed4e04f..23282b1 100644
--- a/tests/testthat.R
+++ b/tests/testthat.R
@@ -1,4 +1,3 @@
 library(testthat)
-library(subtools)
 
 test_check("subtools")

From 4f51a8d2b36373b28fa2df1e8c12f55fd6072cfb Mon Sep 17 00:00:00 2001
From: AlbanSagouis <sagouis@pm.me>
Date: Fri, 20 Mar 2026 15:27:17 +0100
Subject: [PATCH 3/4] CRAN submission

---
 DESCRIPTION                 |  6 ++---
 R/assert_objects.R          | 28 ++++++++++++++++++----
 R/read_subtitles.R          |  7 ++++++
 R/unnest_tokens.R           |  3 +++
 R/utils_regexes.R           | 46 +++++++++++++++++++++++++++++++++----
 R/utils_time.R              | 12 +++++++++-
 R/write_subtitles.R         |  2 ++
 codemeta.json               |  2 +-
 cran-comments.md            |  6 +++++
 man/as_subtitle.Rd          |  3 +++
 man/get_subtitles_info.Rd   |  3 +++
 man/print.multisubtitles.Rd |  3 +++
 man/unnest_tokens.Rd        |  2 ++
 man/write_subtitles.Rd      |  3 +++
 14 files changed, 112 insertions(+), 14 deletions(-)

diff --git a/DESCRIPTION b/DESCRIPTION
index fbadd6f..385287a 100644
--- a/DESCRIPTION
+++ b/DESCRIPTION
@@ -13,9 +13,9 @@ Authors@R: c(
              comment = c(ORCID = "0000-0002-3827-1063"))
     )
 Maintainer: Francois Keck <francois.keck@gmail.com>
-Description: A collection of functions to read, write and manipulate video subtitles.
-    Supported formats include 'srt', 'subrip', 'sub', 'subviewer', 'microdvd',
-    'ssa', 'ass', 'substation', 'vtt', and 'webvtt'.
+Description: A collection of functions to read, write and manipulate video
+    subtitles. Supported formats include 'srt', 'subrip', 'sub', 'subviewer',
+    'microdvd', 'ssa', 'ass', 'substation', 'vtt', and 'webvtt'.
 Language: en-GB
 License: GPL-3
 LazyData: TRUE
diff --git a/R/assert_objects.R b/R/assert_objects.R
index 7bb219f..1188237 100644
--- a/R/assert_objects.R
+++ b/R/assert_objects.R
@@ -1,7 +1,15 @@
-# .assert_subtitles
-# .extract_metadata
-
-# Sanity check for subtitles objects
+#' Validate a subtitles object
+#'
+#' Checks that \code{x} inherits from both \code{"subtitles"} and \code{"data.frame"},
+#' has the four required columns (\code{ID}, \code{Timecode_in}, \code{Timecode_out},
+#' \code{Text_content}), and that the two timecode columns are of class \code{"hms"}.
+#' Stops with an informative error message if any check fails.
+#'
+#' @param x an object to validate.
+#'
+#' @returns Called for its side effects (validation). Returns \code{NULL} invisibly.
+#'
+#' @noRd
 .assert_subtitles <- function(x) {
   if (!is(x, "subtitles")) {
     stop("A subtitles object must inherit from class \"subtitles\".")
@@ -35,7 +43,17 @@
   }
 }
 
-#extract metadata columns from a subtitles object
+#' Extract metadata columns from a subtitles object
+#'
+#' Returns all columns that are not part of the core subtitle structure
+#' (\code{ID}, \code{Timecode_in}, \code{Timecode_out}, \code{Text_content}).
+#'
+#' @param x a \code{subtitles} object.
+#'
+#' @returns A data frame (or tibble) containing only the metadata columns of \code{x}.
+#' If there are no metadata columns, an empty data frame is returned.
+#'
+#' @noRd
 extract_metadata <- function(x) {
   sub_names <- c("ID", "Timecode_in", "Timecode_out", "Text_content")
   md_names <- setdiff(colnames(x), sub_names)
diff --git a/R/read_subtitles.R b/R/read_subtitles.R
index cdc172b..6cf7028 100644
--- a/R/read_subtitles.R
+++ b/R/read_subtitles.R
@@ -14,6 +14,9 @@
 #' @param encoding the name of the encoding to be used. Default is "\code{auto}" and
 #' uses \code{\link[readr]{guess_encoding}} to detect encoding.
 #' @param ... passed on to downstream methods.
+#'
+#' @returns An object of class \code{subtitles} (see \code{\link{subtitles}}).
+#'
 #' @importFrom utils read.csv
 #' @export
 #' @examples
@@ -431,6 +434,8 @@ subtitles <- function(
 #' @param printlen the maximum number of subtitles to print.
 #' @param ... further arguments passed to or from other methods.
 #'
+#' @returns Called for its side effects (printing to the console). Returns \code{NULL} invisibly.
+#'
 #' @examples
 #' f <- system.file("extdata", "ex_subrip.srt", package = "subtools")
 #' s <- read_subtitles(f)
@@ -455,6 +460,8 @@ print.multisubtitles <- function(x, printlen = 10L, ...) {
 #'
 #' @param x a \code{subtitles} or \code{multisubtitles} object.
 #'
+#' @returns Called for its side effects (printing to the console). Returns \code{NULL} invisibly.
+#'
 #' @examples
 #' s <- read_subtitles(
 #'   system.file("extdata", "ex_subrip.srt", package = "subtools")
diff --git a/R/unnest_tokens.R b/R/unnest_tokens.R
index 97c96e7..ca2c505 100644
--- a/R/unnest_tokens.R
+++ b/R/unnest_tokens.R
@@ -162,6 +162,9 @@ unnest_tokens.subtitles <- function(
 #' The default method (\code{unnest_tokens.default}) delegates to the original implementation.
 #' See "?unnest_tokens.subtitles" for the \code{subtools} specific documentation.
 #' @inheritParams tidytext::unnest_tokens
+#'
+#' @returns A tibble.
+#'
 #' @export
 unnest_tokens <- function(
   tbl,
diff --git a/R/utils_regexes.R b/R/utils_regexes.R
index 3d2fe82..08afea1 100644
--- a/R/utils_regexes.R
+++ b/R/utils_regexes.R
@@ -1,11 +1,28 @@
-# Extract file name from dir paths
+#' Extract the file name from a path
+#'
+#' Strips trailing slashes and returns the last path component.
+#'
+#' @param x a character vector of file or directory paths.
+#'
+#' @returns A character vector of file names, the same length as \code{x}.
+#'
+#' @noRd
 .extr_filename <- function(x) {
   x <- gsub("/+$", "", x)
   x <- regmatches(x, regexpr("([^/]+$)", x))
   return(x)
 }
 
-# Extract extension from file name
+#' Extract the extension from a file name
+#'
+#' Returns the part of the file name after the last dot (lower-case alphanumeric only).
+#'
+#' @param x a character vector of file names or paths.
+#'
+#' @returns A character vector of file extensions (without the leading dot),
+#' the same length as \code{x}.
+#'
+#' @noRd
 .extr_extension <- function(x) {
   x <- sub("[?#].*$", "", x)
   is_url <- grepl("^[[:alpha:]][[:alnum:].+-]*://", x)
@@ -90,7 +107,18 @@
   return(res)
 }
 
-# Extract Episode number
+#' Extract episode number from file paths
+#'
+#' Parses the file name component of each path and attempts to detect the episode
+#' number using four common naming conventions:
+#' \code{E01}, \code{EPISODE.2}, \code{S03E05}, and \code{2x05}.
+#' Returns \code{NA} for paths where no convention matches.
+#'
+#' @param x a character vector of file or directory paths.
+#'
+#' @returns A numeric vector of episode numbers, the same length as \code{x}.
+#'
+#' @noRd
 .extr_enum <- function(x) {
   x <- .extr_filename(x)
   x <- toupper(x)
@@ -129,7 +157,17 @@
 }
 
 
-# For WebVTT parsing: select cue blocks only (drop REGION, STYLE, NOTE)
+#' Test whether a string is a WebVTT cue timing line
+#'
+#' Used during WebVTT parsing to identify cue blocks and filter out
+#' \code{REGION}, \code{STYLE}, and \code{NOTE} blocks.
+#'
+#' @param x a single character string (or \code{NA}).
+#'
+#' @returns A single logical: \code{TRUE} if \code{x} matches the WebVTT cue timing
+#' pattern, \code{FALSE} otherwise (including when \code{x} is \code{NA}).
+#'
+#' @noRd
 .test_cuetiming <- function(x) {
   if (is.na(x)) {
     res <- FALSE
diff --git a/R/utils_time.R b/R/utils_time.R
index e4eb48f..ae51373 100644
--- a/R/utils_time.R
+++ b/R/utils_time.R
@@ -1,4 +1,14 @@
-# Format time as HH:MM:SS.mS
+#' Parse subtitle timecode strings into hms objects
+#'
+#' Accepts timecode strings in \code{HH:MM:SS.mS} or \code{MM:SS.mS} format
+#' (comma as decimal separator is also accepted). Missing hour components are
+#' padded to zero.
+#'
+#' @param x a character vector of timecode strings.
+#'
+#' @returns An \code{hms} vector (from the \pkg{hms} package), the same length as \code{x}.
+#'
+#' @noRd
 .format_subtime <- function(x) {
   x <- gsub(",", ".", x)
   x <- strsplit(x, split = ":")
diff --git a/R/write_subtitles.R b/R/write_subtitles.R
index 021edb6..8bf60bb 100644
--- a/R/write_subtitles.R
+++ b/R/write_subtitles.R
@@ -8,6 +8,8 @@
 #' Not used (only SubRip format is currently implemented).
 #' @param encoding the name of the encoding to be used.
 #'
+#' @returns Called for its side effects (writing to \code{file}). Returns \code{NULL} invisibly.
+#'
 #' @export
 #'
 write_subtitles <- function(x, file, format = "srt", encoding = "UTF-8") {
diff --git a/codemeta.json b/codemeta.json
index c669143..21f9ecf 100644
--- a/codemeta.json
+++ b/codemeta.json
@@ -205,7 +205,7 @@
   },
   "applicationCategory": "TextProcessing",
   "keywords": ["subtitles", "video", "text", "srt", "vtt", "ssa", "naturallanguageprocessing"],
-  "fileSize": "183.292KB",
+  "fileSize": "186.925KB",
   "codeRepository": "https://github.com/fkeck/subtools",
   "releaseNotes": "https://github.com/fkeck/subtools/blob/master/NEWS.md",
   "readme": "https://github.com/fkeck/subtools/blob/main/README.md",
diff --git a/cran-comments.md b/cran-comments.md
index 858617d..87d032b 100644
--- a/cran-comments.md
+++ b/cran-comments.md
@@ -3,3 +3,9 @@
 0 errors | 0 warnings | 1 note
 
 * This is a new release.
+
+All functions now have a @returns value.
+
+Thank you for taking the time to review our package.
+
+François et Alban
diff --git a/man/as_subtitle.Rd b/man/as_subtitle.Rd
index 65b2ea5..decd398 100644
--- a/man/as_subtitle.Rd
+++ b/man/as_subtitle.Rd
@@ -57,6 +57,9 @@ uses \code{\link[readr]{guess_encoding}} to detect encoding.}
 
 \item{...}{passed on to downstream methods.}
 }
+\value{
+An object of class \code{subtitles} (see \code{\link{subtitles}}).
+}
 \description{
 Convert an R object to a \code{subtitles} object
 }
diff --git a/man/get_subtitles_info.Rd b/man/get_subtitles_info.Rd
index 17a6556..a856b3a 100644
--- a/man/get_subtitles_info.Rd
+++ b/man/get_subtitles_info.Rd
@@ -9,6 +9,9 @@ get_subtitles_info(x)
 \arguments{
 \item{x}{a \code{subtitles} or \code{multisubtitles} object.}
 }
+\value{
+Called for its side effects (printing to the console). Returns \code{NULL} invisibly.
+}
 \description{
 Get basic informations for subtitle objects
 }
diff --git a/man/print.multisubtitles.Rd b/man/print.multisubtitles.Rd
index 13d6feb..fa32631 100644
--- a/man/print.multisubtitles.Rd
+++ b/man/print.multisubtitles.Rd
@@ -13,6 +13,9 @@
 
 \item{...}{further arguments passed to or from other methods.}
 }
+\value{
+Called for its side effects (printing to the console). Returns \code{NULL} invisibly.
+}
 \description{
 Print method for multisubtitles
 }
diff --git a/man/unnest_tokens.Rd b/man/unnest_tokens.Rd
index 8ff0196..e6c2e9a 100644
--- a/man/unnest_tokens.Rd
+++ b/man/unnest_tokens.Rd
@@ -89,6 +89,8 @@ and \code{pattern} for "regex".}
 to take into account the split of the input column.}
 }
 \value{
+A tibble.
+
 A tibble.
 }
 \description{
diff --git a/man/write_subtitles.Rd b/man/write_subtitles.Rd
index 33a627e..2d9425b 100644
--- a/man/write_subtitles.Rd
+++ b/man/write_subtitles.Rd
@@ -16,6 +16,9 @@ Not used (only SubRip format is currently implemented).}
 
 \item{encoding}{the name of the encoding to be used.}
 }
+\value{
+Called for its side effects (writing to \code{file}). Returns \code{NULL} invisibly.
+}
 \description{
 This function writes a \code{subtitles} object in a file.
 }

From 687d11fe441e79edee74dd16f18770e319d69b80 Mon Sep 17 00:00:00 2001
From: AlbanSagouis <sagouis@pm.me>
Date: Wed, 7 Oct 2026 10:42:50 +0200
Subject: [PATCH 4/4] Ignore CRAN-SUBMISSION and README.html

---
 .gitignore | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/.gitignore b/.gitignore
index dc92163..fdb087a 100644
--- a/.gitignore
+++ b/.gitignore
@@ -93,3 +93,5 @@ $RECYCLE.BIN/
 
 /.quarto/
 **/*.quarto_ipynb
+CRAN-SUBMISSION
+README.html