Provide an opt-in way to warn if exported functions are missing `@examples` or `@returns`

[DavisVaughan]

This is particularly important for a first CRAN release, where this goes by silently in R CMD Check but is something CRAN will reject you for 100% of the time.

It could be part of the roxygen note bits we put in the DESCRIPTION file, like:

• Roxygen: list(markdown = TRUE, warn_no_return = TRUE, warn_no_examples = TRUE)
• Hadley also suggested it may be a bit more general, like cran_warnings = TRUE

Then usethis::create_package() could set this for you automatically, or some other related usethis function.

This comes up a lot:

• https://twitter.com/JosiahParry/status/1514941441570713605?s=20&t=5j_OCKy4Se-A2fCH5wAJCQ
• It has been a part of the extra checks list for a while https://github.com/DavisVaughan/extrachecks

[hadley]

The only thing that would make this hard to implement is that the warning will come from an .Rd "topic", but we don't currently have a good way to refer this back to the block or blocks that generated it. So before implementing this, probably need to soup up backref to store the complete block reference (filename + line number + alias) while continuing to write just the file name (to avoid a bunch of unimportant diffs when changing code org). Would then also need to use that better info in the various @inherit warnings.

Rough outline:

1. Capture more data in roxy_tag_backref, most importantly as automatically added in block_find_object()
2. Introduce new warn_roxy_topic() that uses in this info
3. Use warn_roxy_topic() in rd-inherits.R
4. Add final checking step to roclet_process.roclet_rd that warnings if no @returns or @examples blocks.

Then just need to figure out what option to use turn this on.

[hadley]

If we implemented these enhanced backrefs, we can also use for the @inherit warnings.

[jennybc]

When/if we do this, nudge folks to replace @return with @returns (yeah?).

[DavisVaughan]

^ I seem to be hardwired to use @return https://cs.github.com/r-lib/clock?q=%40return, I only somewhat recently heard from Hadley that he prefers @returns

[EllaKaye]

This would be a really welcome addition! The issue has been quiet for a while. Is implementing this still on the cards?

[hadley]

@EllaKaye roxygen2 in general has been quiet for a while. This is something I'd definitely consider when I'm next working on roxygen2.