Calling methods on resources with arg list throws error

[wooldridge]

If you call the methods on resources:

get()
post()
put()
remove()

with a list of arguments, e.g.:

db.resources.get('testService', {a: 1, b: 2})
  .result(function(response){
    console.log(JSON.stringify(response, null, 2));
  });

an error is thrown:

Error: no name for executing resource service

When arguments are passed in as a single object, all is OK, e.g.:

db.resources.get({name: 'testService', params: {a: 1, b: 2}})
  .result(function(response){
    console.log(JSON.stringify(response, null, 2));
  });

[kcoleman-marklogic]

Isn't that WAI? At least as far as requiring you to use a call obj if you want to pass in params. The error message could certainly be better. :)

That is the usage I documented, at any rate. It's also consistent with the spec from 8.0, which shows this usage:

db.resources.get({name:..., params:{...}, txid:...})

This is pretty typical of the API, IIRC. You have to fallback on a call object once you stray from the bone simple use case.

[wooldridge]

Thanks for the input, @kcoleman-marklogic. Your example from the spec makes the expected usage very clear to me:

db.resources.get({name:..., params:{...}, txid:...})

This signature from the jsdocs tells me I should do something different:

get(name, params, txid) -> {ResultProvider}

This may be a limitation of jsdocs.

For now, I'm going to push this issue out because for me it speaks to making it clearer across the docs that the call object is the expected usage.

I also see that the issue probably can't be "fixed" as I had thought (i.e., make positional params always possible) because of the mix of optional parameter data types in some of the methods.

[kcoleman-marklogic]

FWIW, I think there are some other places where we try to finesse this limitation with the JSDoc through words.

For example, take a look at Documents.remove: http://docs.marklogic.com/jsdoc/documents.html#remove. There, we say "... takes a configuration object with the following named parameters or, as a shortcut, one or more uri strings or an array of uri strings".

Of course, that pre-supposes you understand that "named parameters" means a call object. I have no idea if that's a safe assumption for a Node.js developer or not.

A lot of this could be mitigated by including simple examples of the accepted call forms in the JSDoc. IDK how hard or easy that would be as I'm not very conversant with the markup. Erik got saddled with all that work back at the beginning.

[wooldridge]

This might be relevant:

http://usejsdoc.org/tags-param.html#parameters-with-properties

[kcoleman-marklogic]

Great find! I think that has a lot of potential to address some of the call object confusion. It probably still can't help with the "call object or these shortcuts" problem, but it is certainly worth experimenting with.

[ehennum]

Added an explanatory sentence to the JSDoc for each of the resource execution methods.

Given that Data Services endpoints offer a better way to execute code on the server, it's better not to risk destabilizing the implementation by changing the argument parsing.

[ehennum]

Should cause no regressions.