merge multiple different types of @describeIn in one minidesc

[maxheld83]

This PR extends @describeIn to allow the documentation of both methods and (other) functions in a minidesc.

This closes #1181.
It goes further than the original issue: rather than extending the fallback behavior (everthing treated as a function), this now creates subsections for the separate types of functions.

I think this is quite helpful, such as when documenting together a class constructor (as the destination), some methods and some helpers (normal functions).
For a real-use case, see our doi functions.

This PR makes a couple of user-facing changes:

1. It is more generous: Separate kinds of functions are now listed under separate subsection headings.
   It should not be possible to get more than 2 subheadings though.
2. It is stricter: Only methods which actually pertain to the constructor or generic in question are listed as methods.
3. It is more explicit: The subheading will now remind users what generic/class is being extended.
   (I think the "by class"/"by generic" language alone could be a little hard to wrap your head around).
4. I've expanded the documentation. (I think that's where most of the net line gain comes from).

And some internal changes:

1. The logic, data structure and formatting are now maybe more separated out. It should be relatively easy to change the formatting going forward.
2. Instead of storing in the data structure whether the result should be organized by type = c("generic", "class"), the data structure now records whether a given source function extends the destination function.
   To be precise, extends records wether a source method actually corresponds to the generic or constructor in the destination.
   Labels and subheadings are then generated from this information in the formatting functions.

---

A couple of things remain to be done before this is ready for review:

• testing
• real-world testing / maturing
• write a proper justification for this PR
• fix intermittent testthat warning about open connections (unrelated, see repeated test runs in same session may raise warnings #1189)
• proofreading
• code style review
• also show class name in subtitle
• allow partial matching for S3 classes to constructor.
  Typical case: constructor is called class(), but class is called pkg_class() as recommended.
• fix build fails (argh, stringsAsFactors 😾)
  The remaining build fails (Ubuntu-16.04 3.2, macOS-latest (devel)) appear to be unrelated, intermittent and/or stemming from missing dependencies.

Then, once in review (if I even get that far) I have some comments / questions:

• the example roxygen2 blocks are programmatically reused between tests and vignette.
  This does not seem to be recommended in r-lib/tidyverse as per offer idiom to reuse fixture / setup code in vignettes, examples, docs testthat#1308, because it makes the test-*.R files harder to read.
  However, in this case, the pattern is already used with several tests/testthat/roxygen-block-*.R , so perhaps it's ok?
  If not, I'll re-duplicate these, if the rest is OKed.
  (Re-duplication is required).
• I've added brio to DESCRIPTION, though I think it already comes via testthat, so it should not bloat the actual dependency graph.
• I'm not too happy with section heading. "Function Group" ... any better ideas? Or maybe no section heading for but just the subheadings (as section headings)?
• This would be a good use case for snapshot testing, I guess, but roxygen2 doesn't seem to use testthat edition 3 yet.
  Happy to add it.
• Currently, the minidesc section will always be nested, even if there is only one subsection (as may often be the case).
  This could be changed easily; my rationale was that it might be confusing for users if the structure changes depending on the content.
  But the two levels of headings do take up a fair bit of space, which isn't great.
• someone with more experience using S4 than me should look over the parts of the PR pertaining to S4.

[maxheld83]

so far, just added a failing test to document that this is being worked on.

[maxheld83]

this now broadly works (I think), but see above todos.

[maxheld83]

I probably won't have the time to work on this during the current release window (@hadley mentioned around April 22, 2022 as a target release).

The remaining todos are:

• resolve merge conflicts
• re-duplicate the (currently) code chunks currently shared between documentation and testing

Before I do these, I will wait for some feedback on this PR, whether:

• the feature is even desirable
• my overall approach to add the feature is sound (see questions listed above).

[hadley]

I've only done a fairly quick skim but I think overall the aims and the implementation are good. There's small stuff that could be improved, but the overall "shape" seems looks good to me.

[hadley]

@maxheld83 would you mind taking a look through the snapshot tests to make sure that I've stayed roughly true to your original vision? I changed the subsections to sections (since I think most functions will only have one, and it will appear more prominent in (e.g.) the pkgdown documentation), and I always display the full function name (since I that seemed less confusing to me).

[hadley]

Fixes #1370

[maxheld83]

@hadley

would you mind taking a look through the snapshot tests to make sure that I've stayed roughly true to your original vision?

absolutely ☑️

I changed the subsections to sections (since I think most functions will only have one, and it will appear more prominent in (e.g.) the pkgdown documentation)

Agreed this makes more sense / looks cleaner.

[maxheld83]

🙏 thank you so much for taking this on @hadley and bringing it to completion!
And apologies for the "clever" reuse of code chunks between docs/testing that you had to inline.