Common specific `@examplesIf`: `@examplesIfInteractive`, `@examplesIfInstalled` + easier way to define one's own?

[maelle]

I was wondering whether common use cases of @examplesIf could be implemented in roxygen2 as new tags.

• @examplesIf interactive(): https://github.com/search?q=%22%40examplesIf+interactive%28%29%22+user%3Acran&type=code&ref=advsearch
• @examplesIf rlang::is_installed (less good example as it relies on a dependency): https://github.com/search?q=%22%40examplesIf+rlang%3A%3Ais_installed%22+user%3Acran&type=code&ref=advsearch
• @examplesIf identical(Sys.getenv("NOT_CRAN"), "true")

Now if in a package one has a special way to skip examples, I see @gaborcsardi recommended creating an internal function in #1242 (comment)

• could this approach be documented when introducing @examplesIf, as it's simple and useful, but also not necessarily obvious you can do this. (we're more often told ::: is bad) (https://github.com/DavisVaughan/extrachecks?tab=readme-ov-file#you-used-dontrun-in-an-example-and-got-a-note-about-that hints at a similar solution but with an exported function and without @examplesIf).
• could one define a whole new tag in a package without importing roxygen2? (I only know this about adding new tags: https://masalmon.eu/2024/09/03/roxygen2-custom-tag/)

[gaborcsardi]

I would say probably not.

For simple ones that are a single function call or an expression, there isn't a big advantage. I am not sure if @examplesIfInteractive is any better than @examplesIf interactive().

For more complicated ones, like @examplesIfInstalled, where would the code live? E.g. the code that checks if the package is installed? Embedded into the manual page? The package would need to import roxygen2? roxygen2 would add an auto-generated .R file to your project? None of these seem very good to me.

[maelle]

It makes sense, thank you. What about documenting the approach of using an unexported function as criterion?

[gaborcsardi]

Maybe. A CRAN reviewer once told me to remove the :::, so I had to use asNamespace(...)$... instead. They probably grep the .R files for :::.