docs: document setup argument and two-pass mechanism in printing vignette#847
Open
LeonidasZhak wants to merge 2 commits into
Open
docs: document setup argument and two-pass mechanism in printing vignette#847LeonidasZhak wants to merge 2 commits into
LeonidasZhak wants to merge 2 commits into
Conversation
Add @return documentation tags to exported functions whose generated Rd files lacked \value sections. R CMD check --as-cran notes missing \value for exported functions; this is also a CRAN submission requirement. Functions documented: - ctl_new_pillar_list(): list of pillar objects - new_pillar_component()/pillar_component(): pillar_component object - new_pillar_shaft(): pillar shaft object - pillar_shaft(): pillar shaft object - new_pillar_title(): pillar_title object - new_pillar_type(): pillar_type object - format_type_sum(): styled character string - scale_x_num()/scale_y_num(): ggplot2 scale object Also regenerated all Rd files to include pre-existing @return tags that were present in the R source but not reflected in man pages.
…ette
Document the setup argument of tbl_format_setup() and the
two-pass formatting mechanism in vignette("printing").
Also link to vignette("extending") as requested by maintainer.
Fixes r-lib#731
There was a problem hiding this comment.
Pull request overview
This PR expands the package documentation around pillar’s printing/formatting internals, primarily by documenting the setup/two-pass mechanism in the printing vignette and by adding missing @return/\value{} sections across several help topics.
Changes:
- Document the
setupargument and the two-pass setup mechanism invignette("printing"), and add a pointer tovignette("extending"). - Add
@returntags to multiple roxygen blocks and propagate them into the corresponding generated.Rdfiles. - Fix a documentation typo (“ANYI” → “ANSI”) and add return-value documentation for several helpers.
Reviewed changes
Copilot reviewed 23 out of 37 changed files in this pull request and generated 4 comments.
Show a summary per file
| File | Description |
|---|---|
| vignettes/printing.Rmd | Adds narrative and source excerpts documenting the setup argument and two-pass formatting mechanism. |
| R/type.R | Adds @return for new_pillar_type() and format_type_sum(). |
| R/type-sum.R | Adds @return for type_sum(), obj_sum(), and size_sum(). |
| R/title.R | Adds @return for new_pillar_title(). |
| R/tbl-format-setup.R | Adds @return for tbl_nrow(). |
| R/styles.R | Adds @return for styling helpers (e.g., style_subtle()). |
| R/shaft-.R | Adds @return for new_pillar_shaft() and pillar_shaft(). |
| R/ornament.R | Fixes “ANSI” typo and adds @return for new_ornament(). |
| R/num.R | Adds @return for num() / set_num_opts() docs. |
| R/ggplot2.R | Adds @return for the ggplot2 scale helper. |
| R/extent.R | Adds @return for get_extent(), get_max_extent(), and align(). |
| R/dim.R | Adds @return for dim_desc(). |
| R/ctl_pillar.R | Adds @return for pillar() and new_pillar(). |
| R/ctl_pillar_component.R | Adds @return for pillar_component() constructor docs. |
| R/ctl_new_pillar.R | Adds @return for ctl_new_rowid_pillar() docs. |
| R/ctl_new_pillar_list.R | Adds @return for list-pillar constructor docs. |
| R/char.R | Adds @return for char() / set_char_opts() docs. |
| man/type_sum.Rd | Adds a \value{} section for type_sum()/obj_sum()/size_sum(). |
| man/tbl_nrow.Rd | Adds a \value{} section for tbl_nrow(). |
| man/style_subtle.Rd | Adds a \value{} section for styling helpers. |
| man/scale_x_num.Rd | Adds a \value{} section for the ggplot2 scale helper. |
| man/pillar.Rd | Adds a \value{} section for pillar(). |
| man/pillar_shaft.Rd | Adds a \value{} section for pillar_shaft(). |
| man/num.Rd | Adds a \value{} section for num() / set_num_opts(). |
| man/new_pillar.Rd | Adds a \value{} section for new_pillar(). |
| man/new_pillar_type.Rd | Adds a \value{} section for new_pillar_type(). |
| man/new_pillar_title.Rd | Adds a \value{} section for new_pillar_title(). |
| man/new_pillar_shaft.Rd | Adds a \value{} section for new_pillar_shaft(). |
| man/new_pillar_component.Rd | Adds a \value{} section for new_pillar_component(). |
| man/new_ornament.Rd | Adds a \value{} section for new_ornament() and updates ANSI wording. |
| man/get_extent.Rd | Adds \value{} details for get_extent() / get_max_extent(). |
| man/format_type_sum.Rd | Adds a \value{} section for format_type_sum(). |
| man/dim_desc.Rd | Adds a \value{} section for dim_desc(). |
| man/ctl_new_pillar.Rd | Adds a \value{} section for ctl_new_rowid_pillar(). |
| man/ctl_new_pillar_list.Rd | Adds a \value{} section for ctl_new_pillar_list(). |
| man/char.Rd | Adds a \value{} section for char() / set_char_opts(). |
| man/align.Rd | Adds a \value{} section for align(). |
Files not reviewed (14)
- man/align.Rd: Language not supported
- man/char.Rd: Language not supported
- man/ctl_new_pillar.Rd: Language not supported
- man/ctl_new_pillar_list.Rd: Language not supported
- man/dim_desc.Rd: Language not supported
- man/format_type_sum.Rd: Language not supported
- man/get_extent.Rd: Language not supported
- man/new_ornament.Rd: Language not supported
- man/new_pillar.Rd: Language not supported
- man/new_pillar_component.Rd: Language not supported
- man/new_pillar_shaft.Rd: Language not supported
- man/new_pillar_title.Rd: Language not supported
- man/new_pillar_type.Rd: Language not supported
- man/num.Rd: Language not supported
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+138
to
+141
| In the first pass, `format_tbl()` calls `tbl_format_setup()` with `setup` set to an expression that evaluates to `NULL`. | ||
| If the method evaluates the `setup` argument and finds `NULL`, it returns a minimal setup object containing only the header information (via `tbl_sum()`). | ||
| The header is then formatted and displayed immediately, so the user sees output right away. | ||
|
|
Comment on lines
+133
to
+136
| ### The `setup` argument and the two-pass mechanism | ||
|
|
||
| The `setup` argument of `tbl_format_setup()` enables a two-pass formatting mechanism. | ||
| This is particularly useful for lazy tables (e.g., database tables) where computing the total number of rows or the full body can be expensive. |
Comment on lines
9
to
11
| #' @param x A character vector with formatting, | ||
| #' can use ANYI styles e.g provided by the \pkg{cli} package. | ||
| #' can use ANSI styles e.g provided by the \pkg{cli} package. | ||
| #' |
Comment on lines
10
to
12
| \item{x}{A character vector with formatting, | ||
| can use ANYI styles e.g provided by the \pkg{cli} package.} | ||
| can use ANSI styles e.g provided by the \pkg{cli} package.} | ||
|
|
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.
Fixes #731.
Summary
setupargument oftbl_format_setup()and the two-pass formatting mechanism invignette("printing")vignette("extending")as requested by maintainer in commentformat_tblsource to illustrate the two-pass mechanism in actionChanges
vignettes/printing.Rmd: +22 lines documenting the setup argument and two-pass mechanismChecks
rmarkdown::render("vignettes/printing.Rmd")renders successfully