Currently, the init(...) call of every trace accepts a ridiculously large number of parameters (see #1 for details). It would be nice if the documentation visible in XCode after the option click option-click and eventually in Jazzy displayed the full list of the parameters. Each with a simple, single sentence description.
The purpose is two fold - first to give a brief explanation of functionality and second to provide a way to quickly lookup the order of parameters. Unfortunately, Swift in contrast to Python keyword arguments, requires that all calls of a function have parameter order identical to the definition.
Not following the order frequently leads to a strange and misleading compiler errors and a general sub-par user experience. The code-(de)generated initializers tend to have around 50 of these order-sensitive arguments. Sorting them is even not fun when one has to scroll up-and-down the source code of the constructed trace.
Desired result should follow the XCode markdown format and look something like this:
/// A simplified Scatter trace initializer.
///
/// - Parameters:
/// - name: Name of the trace that shows up in the legend.
/// - x: Plotable vector of `x` values.
/// - y: Plotable vector of `y` values.
/// - marker: Single marker style or an array of individual styles for each data point.
/// - line: Style of the trace line.
/// - mode: Arbitrary combination of `.line`, `.marker`, or `.text`.
///
init(name: String? = nil, x: XData? = nil, y: YData? = nil,
marker: Marker? = nil, line: Line? = nil, mode: Mode? = nil)
vojtamolda
commented
4 years ago
Currently, the
init(...)call of every trace accepts a ridiculously large number of parameters (see #1 for details). It would be nice if the documentation visible in XCode after the option click option-click and eventually in Jazzy displayed the full list of the parameters. Each with a simple, single sentence description.The purpose is two fold - first to give a brief explanation of functionality and second to provide a way to quickly lookup the order of parameters. Unfortunately, Swift in contrast to Python keyword arguments, requires that all calls of a function have parameter order identical to the definition.
Not following the order frequently leads to a strange and misleading compiler errors and a general sub-par user experience. The code-(de)generated initializers tend to have around 50 of these order-sensitive arguments. Sorting them is even not fun when one has to scroll up-and-down the source code of the constructed trace.
Desired result should follow the XCode markdown format and look something like this: