Consider adding the option names to the Command Syntax section on API pages

[larkost]

Currently in the API pages the "Command syntax" labels the options only as options. This is probably a space-saving means for the main page, and that makes sense there. But I would rather see the options spelled out (including the defaults), as they are in the Python docs. For example I would like to see the connect Python page go from:

r.connect(options) → connection

to:

r.connect(host='localhost', port=28015, db='test', user='admin', password='', timeout=20, ssl=None) → connection

[danielmewes]

Since the main (index) page is now auto-generated from the individual pages, we need to weight the benefits of this against the extra work (and potential for mistake) of maintaining the signatures separately for the index and detail pages.

Currently some commands have the full set of options in the syntax (e.g. insert), and others don't (e.g. connect or run). I assume this is depending on how many options there are for the particular command.

I'd like to hear what @chipotle's opinion on this is when he comes back.

[chipotle]

Currently some commands have the full set of options in the syntax (e.g. insert), and others don't (e.g. connect or run). I assume this is depending on how many options there are for the particular command.

Yep. There's no hard and fast rule for this, but once a command gets more than three or four options I tend to take them out of the API header. There's only about a half-dozen commands that this is the case for. The API header for run if we documented everything would look something like this:

query.run(conn[, read_mode="single", time_format="native", profile=False,
durability="soft", group_format="native", noreply=False, db="test",
array_limit=100000, binary_format="native", min_batch_rows=8,
max_batch_rows=<unlimited>, max_batch_seconds=0.5,
first_batch_scaledown_factor=4]) → cursor
query.run(conn[, read_mode="single", time_format="native", profile=False,
durability="soft", group_format="native", noreply=False, db="test",
array_limit=100000, binary_format="native", min_batch_rows=8,
max_batch_rows=<unlimited>, max_batch_seconds=0.5,
first_batch_scaledown_factor=4]) → object

...and while this is admittedly the worst case to pick, I'm not convinced this would aid clarity. I could be convinced otherwise, but we have a couple commands that get into the 6+ option range—and sometimes have more than one form, like run here, and thus have to be repeated for each form.

[danielmewes]

My opinion is that our current signatures are fine (we should maybe standardize on a specific cut-off value for the future, e.g. 4+ options). Consistency is good, but readability also matters.