[Vignette] Name uncommon Arguments in function calls

[discoleo]

Vignette: Incorporate Designs

• minor enhancement;

Uncommon arguments to functions should be named:

• users may be unfamiliar with all function arguments;
• names hidden in the text are difficult to spot;

Example

my_design_blk <- make_design(
    output_format = "blocks",
    nrows = 8, ncols = 12,
    Bacteria = list(c("Str1", "Str2", "Str3",
        "Str4", "Str5", "Str6"),
        2:7,
        2:11,
        "123056",
        FALSE)
)

Enhancement

1. Move the argumetns 2:7 and 2:11 on a single line: very little information is encoded by each line;
2. Name uncommon arguments: byrow = FALSE;
   • the argument may remain unnamed in real practice, but the name is useful in the vignette;

[mikeblazanin]

there are no argument names for arguments passed to make_design via ..., so it would be misleading to put them in.

[discoleo]

Clarification

There are 2 examples: one can infer from the 2nd example the meaning of the parameters. These are also briefly mentioned in the vignette Incorporating Design, but the arguments are not named throughout the vignette.

However, you could easily write a named list:

insted of:

Bacteria = list(c("Str1", "Str2", "Str3",
    "Str4", "Str5", "Str6"),
    2:7,
    2:11,
    "123456",
    FALSE)
# use the pseudo-names:
Bacteria = list(values = c("Str1", "Str2", "Str3",
    "Str4", "Str5", "Str6"),
    rows = 2:7, cols = 2:11,
    pattern = "123456",
    byrow = FALSE)

It is far clearer to the reader. Especially rare arguments (like byrow = FALSE) benefit from the explicit naming. I believe that the naming of the elements of the list will not break the current code.

It is easy to actually use named arguments in the code as well:

Before line 1817 (version 1.3.0 on GitHub):\ if(is.null(names(dots_args[[i]]))) names(dots_args[[i]]) = ...;\ Also possible: You can check if the argument byrow is provided or not; set it explicitly to FALSE in the latter case and access the named arguments.