v1.0 documentation audit - #1209
Merged
Merged
Conversation
Various fixes to processing initial values
…ion-audit # Conflicts: # NEWS.md # R/fit.R # R/model.R # man-roxygen/model-common-args.R # man/fit-method-time.Rd # man/model-method-diagnose.Rd # man/model-method-generate-quantities.Rd # man/model-method-laplace.Rd # man/model-method-optimize.Rd # man/model-method-pathfinder.Rd # man/model-method-sample.Rd # man/model-method-sample_mpi.Rd # man/model-method-variational.Rd
There was a problem hiding this comment.
Pull request overview
This PR refreshes CmdStanR’s user-facing documentation (vignettes + generated Rd) and aligns tests/snapshots with updated messaging and behavior around fitted-object utilities.
Changes:
- Audits and clarifies multiple vignettes (R Markdown/Quarto engines, profiling, posterior draws formats, OpenCL guidance, internals).
- Updates many Rd pages/roxygen outputs for clearer return values, improved wording, and additional cross-references.
- Adjusts runtime behavior and tests/snapshots around file-saving utilities and deprecation warnings.
Reviewed changes
Copilot reviewed 91 out of 104 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| vignettes/r-markdown.Rmd | Clarifies knitr engine usage (incl. Quarto) and mixed RStan/CmdStanR setup. |
| vignettes/profiling.Rmd | Improves Bernoulli example correctness/reproducibility and updates links/wording. |
| vignettes/posterior.Rmd | Updates posterior usage examples and clarifies summary/draws semantics. |
| vignettes/cmdstanr.Rmd | Documentation fixes/clarifications for setup, summary, and methods. |
| vignettes/cmdstanr-internals.Rmd | Safer examples (avoid mutating CmdStan install) and clarified internals. |
| vignettes/children/comparison-with-rstan.md | Refines RStan vs CmdStanR comparison statements. |
| vignettes/articles-online-only/opencl.Rmd | Updates OpenCL guidance and improves reproducibility. |
| tests/testthat/test-utils.R | Adds regression test for copy failure behavior in temp-file copying. |
| tests/testthat/test-threads.R | Converts deprecation warning assertion to snapshot-based expectation. |
| tests/testthat/test-model-pathfinder.R | Updates expectations for Pathfinder single-path auxiliary outputs. |
| tests/testthat/test-model-optimize.R | Removes args no longer applicable to optimize() validation tests. |
| tests/testthat/test-model-compile.R | Fixes grammar in an expected error message. |
| tests/testthat/test-install.R | Converts deprecation warning assertion to snapshot-based expectation. |
| tests/testthat/test-csv.R | Adds snapshot asserting reconstructed Laplace fits error on $mode(). |
| tests/testthat/_snaps/utils.md | New snapshot for copy_temp_files failure message. |
| tests/testthat/_snaps/threads.md | New snapshot for pathfinder threading deprecation warning. |
| tests/testthat/_snaps/install.md | New snapshot for toolchain deprecation warning. |
| tests/testthat/_snaps/csv.md | New snapshot for reconstructed Laplace $mode() error. |
| R/zzz.R | Adds explicit deprecation warning for legacy version-check env/option. |
| R/utils.R | Changes copy_temp_files to error on any copy failure (no partial NA returns). |
| R/path.R | Expands/clarifies path-related return-value and behavior documentation. |
| R/options.R | Clarifies version-check configuration and adds seealso links. |
| R/knitr.R | Documents return values and clarifies required chunk options. |
| R/install.R | Clarifies install/rebuild semantics, return values, and deprecation wording. |
| R/generics.R | Improves developer-facing generic documentation and return semantics. |
| R/file.R | Documentation cleanup and added cross-references. |
| R/example.R | Clarifies accepted method values and adds seealso/return details. |
| R/data.R | Documentation clarifications for JSON writing and draws_to_csv. |
| R/csv.R | Documents reconstructed-fit limitations and blocks Laplace $mode() for CSV fits. |
| NEWS.md | Notes deprecations and documents behavioral/API constraint updates. |
| man/write_stan_json.Rd | Adds value/seealso and minor wording fixes. |
| man/write_stan_file.Rd | Fixes wording and adds seealso section. |
| man/set_cmdstan_path.Rd | Expands value section and clarifies CMDSTAN resolution behavior. |
| man/register_knitr_engine.Rd | Adds value + seealso documentation. |
| man/read_cmdstan_csv.Rd | Documents reconstructed-fit limitations and available methods. |
| man/print_stan_file.Rd | Adds seealso section. |
| man/model-method-variational.Rd | Wording/argument clarifications and updated cross-links. |
| man/model-method-variables.Rd | Wording fixes and additional seealso references. |
| man/model-method-sample.Rd | Clarifies semantics for lp__/initialization/docs consistency. |
| man/model-method-sample_mpi.Rd | Aligns wording/argument docs with sample(). |
| man/model-method-pathfinder.Rd | Updates docs for outputs, defaults, and deprecations. |
| man/model-method-optimize.Rd | Clarifies jacobian/MLE vs MAP wording and removes unsupported args. |
| man/model-method-model-info.Rd | New Rd documenting CmdStanModel information accessors. |
| man/model-method-laplace.Rd | Clarifies jacobian semantics and removes unsupported args. |
| man/model-method-generate-quantities.Rd | Clarifies reuse of CSV paths and default argument behavior. |
| man/model-method-format.Rd | Clarifies backup behavior and return value wording. |
| man/model-method-expose_functions.Rd | Adds value section and wording clarifications. |
| man/model-method-diagnose.Rd | Clarifies output behavior and adds additional seealso guidance. |
| man/model-method-compile.Rd | Clarifies outputs and links to new model-info docs. |
| man/model-method-cmdstan_defaults.Rd | Clarifies parameter docs and CmdStanR naming. |
| man/model-method-check_syntax.Rd | Minor wording fixes. |
| man/install_cmdstan.Rd | Clarifies timeout defaults/returns and deprecation wording. |
| man/fit-method-variable_skeleton.Rd | Adds value section and cleans up seealso. |
| man/fit-method-unconstrain_variables.Rd | Adds value section and seealso cleanup. |
| man/fit-method-unconstrain_draws.Rd | Clarifies args/value and behavior around inc_warmup. |
| man/fit-method-time.Rd | Minor wording tweak. |
| man/fit-method-summary.Rd | Adds print-method aliases/args documentation. |
| man/fit-method-save_output_files.Rd | Documents new error semantics and filename patterns. |
| man/fit-method-save_object.Rd | Clarifies behavior, adds return value, expands examples. |
| man/fit-method-return_codes.Rd | Removes redundant seealso. |
| man/fit-method-profiles.Rd | Removes redundant seealso. |
| man/fit-method-output.Rd | Clarifies value/behavior across fit types. |
| man/fit-method-num_chains.Rd | Clarifies scope beyond MCMC + seealso updates. |
| man/fit-method-mode.Rd | New Rd documenting Laplace $mode() behavior/limitations. |
| man/fit-method-mle.Rd | Clarifies lp__/MAP vs MLE semantics. |
| man/fit-method-metadata.Rd | Adds value section. |
| man/fit-method-materialize.Rd | Adds value section and wording cleanup. |
| man/fit-method-lp.Rd | Clarifies lp__/lp_approx semantics across methods. |
| man/fit-method-log_prob.Rd | Adds value section and clarifies jacobian wording. |
| man/fit-method-init.Rd | Removes redundant seealso. |
| man/fit-method-init_model_methods.Rd | Adds value section. |
| man/fit-method-hessian.Rd | Clarifies title/value and seealso cleanup. |
| man/fit-method-gradients.Rd | Fixes value description. |
| man/fit-method-grad_log_prob.Rd | Adds value section and seealso cleanup. |
| man/fit-method-fitted_params_files.Rd | New Rd for GQ fitted parameter file paths. |
| man/fit-method-draws.Rd | Clarifies draws formats/semantics for additional fit types. |
| man/fit-method-diagnostic_summary.Rd | Fixes quoting/links for diagnostics list and posterior function name. |
| man/fit-method-constrain_variables.Rd | Adds value section and seealso cleanup. |
| man/fit-method-code.Rd | Removes redundant seealso. |
| man/fit-method-cmdstan_summary.Rd | Adds value section and clarifies method applicability. |
| man/eng_cmdstan.Rd | Adds value/seealso and clarifies required chunk options. |
| man/draws_to_csv.Rd | Clarifies basename behavior, comment format, and adds seealso. |
| man/CmdStanVB.Rd | Documents reconstructed-fit limitations and expands method listings. |
| man/cmdstanr-package.Rd | Aligns package-level docs with updated RStan/CmdStanR comparison text. |
| man/cmdstanr_global_options.Rd | Clarifies version-check env var and adds seealso. |
| man/cmdstanr_example.Rd | Clarifies method options/return behavior and adds seealso. |
| man/CmdStanPathfinder.Rd | Documents reconstructed-fit limitations and expands method listings. |
| man/CmdStanModel.Rd | Links to new model-info docs and expands method grouping. |
| man/CmdStanMLE.Rd | Clarifies jacobian semantics, reconstructed-fit limitations, and method listings. |
| man/CmdStanMCMC.Rd | Documents reconstructed-fit limitations and expands method listings. |
| man/CmdStanLaplace.Rd | Documents reconstructed-fit limitations and expands method listings (incl. $mode()). |
| man/CmdStanGQ.Rd | Adds fitted_params_files/num_chains and expands method listings. |
| man/CmdStanDiagnose.Rd | Adds output_files/data_file entries and clarifies lp__ wording. |
| man/cmdstan_model.Rd | Updates example wording (Pathfinder terminology). |
| man/cmdstan_default_path.Rd | Adds seealso section. |
| man/cmdstan_default_install_path.Rd | Wording fix + adds seealso section. |
| man/cmdstan_coercion.Rd | Adds value/seealso and fixes wording. |
| man/as_mcmc.list.Rd | Adds seealso section. |
| man/as_draws.CmdStanMCMC.Rd | Adds value/seealso sections. |
| man-roxygen/model-save-latent-dynamics-arg.R | Adds shared roxygen block for save_latent_dynamics arg docs. |
| man-roxygen/model-sample-args.R | Updates shared docs for fixed_param and diagnostics wording. |
| man-roxygen/model-common-args.R | Updates shared docs for seed/init/output_basename/sig_figs wording. |
Files not reviewed (13)
- man/CmdStanDiagnose.Rd: Generated file
- man/CmdStanGQ.Rd: Generated file
- man/CmdStanLaplace.Rd: Generated file
- man/CmdStanMCMC.Rd: Generated file
- man/CmdStanMLE.Rd: Generated file
- man/CmdStanModel.Rd: Generated file
- man/CmdStanPathfinder.Rd: Generated file
- man/CmdStanVB.Rd: Generated file
- man/as_draws.CmdStanMCMC.Rd: Generated file
- man/as_mcmc.list.Rd: Generated file
- man/cmdstan_coercion.Rd: Generated file
- man/cmdstan_default_install_path.Rd: Generated file
- man/cmdstan_default_path.Rd: Generated file
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Codecov Report❌ Patch coverage is
Additional details and impacted files@@ Coverage Diff @@
## master #1209 +/- ##
==========================================
- Coverage 91.81% 91.62% -0.19%
==========================================
Files 15 15
Lines 6217 6248 +31
==========================================
+ Hits 5708 5725 +17
- Misses 509 523 +14 ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
This tricks R cmd check and avoids warnings
Member
Author
|
note to self: when merging this PR squash the commits! |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Submission Checklist
Summary
This PR contains a ton of small improvements to the documentation. Some are just typos, others are clarifications, others are fixing incorrect statements in the doc, missing
@returnsections, etc.Copyright and Licensing
Please list the copyright holder for the work you are submitting
(this will be you or your assignee, such as a university or company):
Jonah Gabry
By submitting this pull request, the copyright holder is agreeing to
license the submitted work under the following licenses: