Standardize the notation for optional parameters in documentation

[kartikeyakirar]

Based on the discussions regarding the documentation style for indicating optional parameters within pacakge (see details ), it has been suggested that we adopt a unified approach to enhance consistency.

The proposed standard for denoting optional parameters is to follow the format:
@param (`character`) optional ...

[averissimo]

An "edge case" when the type is part of the description should be considered (@chlebowa first mentioned this that comment)

I've tentatively rephrased it like this: (**optional** surrounded by ** for emphasis)

WDYT?

-#' @param input_path optional, (`list`) of the input paths to either: specific files of accepted formats,
+#' @param input_path (`list`) of the input paths, **optional**. Each element can be:

Any suggestions on cases like this?

-#' @param row_facet optional, (`data_extract_spec` or `list` of multiple `data_extract_spec`)
-#'   Which data columns to use for faceting rows.
# a)
+#' @param row_facet (`data_extract_spec` or `list` of multiple `data_extract_spec`)
+#' **optional** specification of the data variable(s) to use for faceting rows.
# or b)
+#' @param row_facet (`data_extract_spec` or `list` of multiple `data_extract_spec`) **optional**.
+#' Specification of the data variable(s) to use for faceting rows.

[kartikeyakirar]

IMO option a) might be more preferable because it integrates the "optional" keyword with the type description . and slightly maintain consistency with input_path example you suggested.

[m7pr]

@insightsengineering/nest-core-dev would we like to tackle this before the release or after?

[m7pr]

ah ok I just saw the PR, so probably before the release #698