Don't restrict specifications to PDF manual

[yihui]

This PR is not super important. I was just wondering if there was a reason that the function specifications were hidden from the HTML help pages. If this was intentional, please feel free to close the PR.

[yihui]

Closing the PR since I learned that the specifications were primarily for developers and not intended for end users. The original idea was probably from Yilong.

[jdblischak]

Adding some extra context, since I had the same suggestion recently.

I recently recommended that the documentation be updated to better distinguish the gs_design_X() functions from the gs_method_X() functions (#500). I had suggested adding the specifications to the HTML docs, but as you also learned today, these developer-docs are too granular to be much help to end users. In fact, in #501, these developer-only docs were simply deleted.

[yihui]

I feel all these specs can be deleted, or changed to ordinary R comments instead of using roxygen docs. I doubt if anyone would ever open the PDF manual to read the specs.

[nanxstats]

I agree this section is weird to have... but maybe for a good reason. I think it was modeled after the proprietary documentation requirements from a legacy language to be as consistent as possible. @elong0527

[elong0527]

The motivation of those spec sections was to follow organization SOP for software development life cycle requirement.

[yihui]

@elong0527 Thanks for the explanation!

This may be an example of Chesterton's fence :) Anyway, if it's important to follow SOP here, I think it may make more sense to develop a special tool similar to roxygen2. That is, we move the specs into the code, mark them as special comments, e.g., comments starting with # - (^\\s*#\\s+-\\s+):

ahr <- function(...) {

  # - Validate if input enrollment rate contains stratum column.
  # - Validate if input enrollment rate contains total duration column.
  res <- pw_info(
    enroll_rate = enroll_rate,
    fail_rate = fail_rate,
    total_duration = total_duration,
    ratio = ratio)

  #> Compute the proportion in each group.
  setDT(res)
  ...
}

Then we can extract the specs for all functions and build a full specs doc for whomever interested in reading them. This should be straightforward to implement (perhaps an afternoon would be enough). Another benefit is that the specs are blended into specific blocks of source code and can help authors/contributors understand the purpose of the code better. In case we need to update the specs or code, we can update them together since they are close to each other.

[elong0527]

Agree that will be a much cleaner solution!

[nanxstats]

Nice discussions. I think we might have already implemented @yihui's proposal internally... 😅 Let me connect you with the code owner @BrianLang via email to see if it's possible to standardized it and build as open source.