fix(#227): clarify when a summary object appears in query results

[wooldridge]

Fixes #227

[kcoleman-marklogic]

I think what you have here is OK, but I wonder:

Are you certain that it is necessary/correct to enumerate those specific options, or is it the case that using withOptions at all (regardless of the options you specify) causes the search response to be returned?

For example, the way to say "just return the search response and no documents" is to use withOptions({category: 'none'}).

I am not sure of the answer. I'm just wary of enumerating if it is not necessary.

[wooldridge]

@kcoleman-marklogic, is there a good place in docs.marklogic.com to link to from the withOptions() description where a user can get more information about how all the properties (or maybe just the key ones) in that method work? To answer questions like, what are the available search options and how do they work? What do you think about doing that? I think Sudhakar's original bug submission points out that this area is complicated and a bit confusing to many who are just looking at the Node.js docs for withOptions().

[wooldridge]

Thanks for your help, @kcoleman-marklogic. I did some more testing with withOptions(). As you point out, the {category: 'none'} option gives you the search summary similar to what is seen with the other four options I mention. The options I don't mention return result docs (in some form or another) but no search summary. I want to address the original issue, which was confusion about when and why summaries appear. I will add a bit more about {category: 'none'}.