Types of parameters in the documentation

[m7pr]

Starting a Discussion since there is no option to open a regular issue.

I am just going through the documentation because of #540 and realized chevron documents parameters with the following object types flag, string, numeric. Those are not names of atomic object types in R. Should we revisit to logical, character, numeric instead?

This is inconsistent as you use character to describe the parameter object type in multiple other places

[m7pr]

I am able to globally substitute (``string``) with (``character``) and do the same for (``flag``) and (``logical``) conversion

[kieranjmartin]

I guess string and flag have meanings in assert that, referring to a character and a logical of length 1 respectively; but I don't know how well this is known by R users

[m7pr]

@kieranjmartin I think we are using checkmate::check_* functions for the detection of object types. I would say string and flag are uncommon for R users as the base atomic object types are called character and logical. The thing is that checkmate has both assert_string and assert_character, as well as assert_flag and assert_logical. checkmate package defines string as a scalar (vector of length 1) character, and flag as a scalar (vector of length 1) logical. Is the usage in chevron consistent with it? Do you treat character and string independently assuming string should be a character of length 1? The same for flag and logical? If no, can I help unifying documentation so it's character everywhere and logical everywhere? Or should we revisit the usage of character and substitute to string if this refers to vectors of length 1 (the same for logical and flag)?

[pawelru]

Note that it is just part of documentation and it has no impact on the actual assertions we are executing. Therefore, it should serve it's goal to document types correctly. I would argue that flag consist of more information than just logical - especially from the perspective of length of objects - flag is of length of 1 whereas logical is unknown. Because of that I would move towards logical(1). In this case I am indifferent between flag and logical(1) - both are good and consists of the same information. The only thing is consistency. As far as I am aware, in all our other packages we are using logical(1) and I would go this way - just because of consistency.

On a side note, I think that it all originated from assertthat and its exported is.* functions. There is only one example that the "types" presented there is more informative than the base R types - namely: count interpreted as a non-negative integer of length of 1 vs logical(1) where we lose the non-negative information.

[BFalquet]

The usage of string and flag is normally already consistent in chevron (plus/minus the inevitable errors) and always denotes a character or logical of length 1. For consistency sake we can adjust that but honestly, I don't see much added value.

[m7pr]

@BFalquet there are places in chevron where you specify the type as character (without the length) but in the end it's a character of length 1, so in your case this should be string in your convention. Check those

split_var (character) variable to split rows by. in split_rows_by_recurive
tlgfname (character) function name of TLG function in gen_args.R