Fix gsSurvPower timing criteria

[keaven]

Summary

• Fix gsSurvPower() timing resolution for explicit minfup, targetN, maxExtension, and minN/minFollowUp workflows.
• Add regression coverage for issues minfup=... in gsSurvPower may not working...? #291, Conflicts of R and targetN in gsSurvPower() #293, Shall we use maxExtension along with plannedCalendarTime and targetEvents in gsSurvPower()? #295, and Can we decide the analysis timing by minimal total sample and minimum follow-up time after the minimal total sample size is reached in gsSurvPower()? #296.
• Document common gsSurvPower() timing pitfalls in the vignette and refresh NEWS/Rd docs.

Closes #291.
Closes #293.
Closes #295.
Closes #296.

Checks

• testthat::test_file("tests/testthat/test-gsSurvPower.R")
• testthat::test_dir("tests/testthat")
• git diff --check
• test-coverage GitHub Action: success
• R-CMD-check.yaml GitHub Action: success across macOS release, Windows release, Ubuntu devel, Ubuntu release, and Ubuntu oldrel-1
• pkgdown devel deploy: success

[jdblischak]

This type of code sounds off alarm bells to me. It shouldn't be this complex to determine if a user supplied an argument. Instead you can do the exact same thing in the line above for determining if alpha was supplied directly to gsSurvPower():

  alpha_provided_by_user <- !is.null(alpha)
  minfup_provided_by_user <- !is.null(minfup)

In general, having these arguments behave differently whether they are directly supplied as an argument to gsSurvPower() or passed via x makes it hard to reason about. There is a comment explaining why this must be done for alpha. Is there a reason why minfup should be ignored if it is supplied via x?

[nanxstats]

The only valid reason I can think of using such a condition is for backward compatibility. For example, minfup and T defaults were changed in gsDesign 3.6.0 (#105), which breaks people's code if they didn't supply the argument before and run under the new version. Not sure if it's necessary here, though.

Fundamentally, I think this is because these are, perhaps inherently, required arguments, and required args shouldn't have defaults.

[jdblischak]

I don't think we need to worry about backwards compatibility here. The default for gsSurvPower() has always been minfup = NULL. Thus is if we want to know if the user supplied it, the simpler !is.null(minfup) will suffice. No need to dynamically obtain the supplied arguments via match.call().