Feature: migration tools

[dgkf]

It would be nice if roxytypes provided migration tools. Just brainstorming what the initial user-facing api might look like, I think something like this would be good:

Default behavior:

Replace all @params with @typed, leaving a blank entry for the type definition.

convert_params()

Resulting in the following changes:

- #' @param var this is the description
+ #' @typed var:
+ #'   this is the description

This will still throw warnings due to all the missing types when you try to document the package, but this is a necessary part of migration.

Pattern matched conversion:

To fine-tune a migration, provide a regular expression to match on the current parameter definitions. If it matches, use the extracted type and description. Otherwise, use another parameter to decide what to do with descriptions that fail to match. Either keep as @param or convert to @typed with a missing type definition.

convert_params(fmt = r"(\(`(?<type>)`\)(?<description>))", unmatched = TRUE) 

Resulting in the following changes:

- #' @param var (`my type`) this is the description
+ #' @typed var: my type
+ #'   this is the description
- #' @param var2 this is an unmatched description
+ #' @typed var2:
+ #'   this is an unmatched description

---

Other considerations

• I don't think any attempts to reflow lines should be made. This might mean the first line of a @typed description leaves excess white space, but I think this is better than trying to holistically handling reflow of arbitrarily formatted descriptions.

[danielinteractive]

Cool, the pattern matched conversion will be super useful :-) I guess based on a branch here I could try this out on a larger package and give feedback.

[dgkf]

Done! (forgot to mark as closed in the PR)