yaml-writing `brief` field in validation steps

[yjunechoe]

I'm unsure whether this used to be supported at all (at least not for the past 2 minor versions), but it seems that brief is not preserved when writing to yaml, unlike e.g., label:

agent <- create_agent(~ small_table) |> 
  col_vals_lt(c(a, c), 5, label = "a label", brief = "a brief")

yaml_agent_string(agent, expanded = FALSE)
#> type: agent
#> tbl: ~small_table
#> tbl_name: ~small_table
#> label: '[2025-01-23|16:02:21]'
#> lang: en
#> locale: en
#> steps:
#> - col_vals_lt:
#>     columns: c(a, c)
#>     value: 5.0
#>     label: a label

yaml_agent_string(agent, expanded = TRUE)
#> type: agent
#> tbl: ~small_table
#> tbl_name: ~small_table
#> label: '[2025-01-23|16:02:21]'
#> lang: en
#> locale: en
#> steps:
#> - col_vals_lt:
#>     columns: c("a")
#>     value: 5.0
#>     label: a label
#> - col_vals_lt:
#>     columns: c("c")
#>     value: 5.0
#>     label: a label

A principled approach to this would seem to also require #273, such that auto-generated briefs can skip being written out.

I'm also surprised that this issue hasn't seen a ticket yet - perhaps not many folks are in the business of customizing and recording briefs? @rich-iannone do you have any thoughts on the status of brief? I'm trying to weigh the pros of adding this feature against the cons of maintenance burden that it might come with :)

[rich-iannone]

I've heard of some people preferring to use the brief field for a longer description of a validation step. Though, I think most would just use the default, automatic generation option (as a good enough description they don't have to write).

It's perhaps for this reason that I didn't preserve brief in the written-out YAML (or, more likely, didn't have a good strategy w.r.t. autobrief at that time). At any rate, I think it really should be part of the pointblank/YAML spec! (and something like what's described in https://github.com/rstudio/pointblank/issues/273 could help).

[yjunechoe]

Thanks for the context! In that case, I'll try to tackle #273 first and come back to the yaml side of things

[jl5000]

I was just about to post a feature request for this as it's functionality I will really need. The auto-generated briefs are great for the simpler column tests, but for col_vals_expr() it really does need bespoke text explaining it.