Alasql: Better SEARCH documentation

[AmyBlankenship]

AlaSQL is based on unpaid voluntary work. Thank you for taking the time to make it better.

The SEARCH documentation gives examples, but without any real documentation of any of the syntax, it's difficult to figure out how to modify it. So for example, it's not clear what the slash really means, and what the trailing slash does (so how do you know where to place it). None of the examples have any clue about how to narrow searches with WHERE clauses. What should references to nested objects look like in a WHERE clause? I looked for larger OrientDB documentation, but I didn't find anything that clarified. The link in the docs that looks like it should point to some larger OrientDB documentation just goes to a limited example. Even if you don't have time to document all this, pointing to the docs of the code that inspired this feature would be really helpful.

[mathiasrw]

@agershun this one is for you

[agershun]

I will prepare wiki page for this.

[AmyBlankenship]

Thanks! I was looking at the SEARCH tests for guidance, and I found an example you gave in SO that wasn't in the tests. The tests could be really helpful for people trying to understand this, but for one thing it's hard to find the right test due to the naming convention. I'd like to help out and add a test for that (and also possibly rename some spec files with your permission), but I am not sure how to set up a project to actually work on a JS library rather than just use it. The tutorials I have managed to find don't address this point. Do you have a favorite reference that you could point me to?

[mathiasrw]

All the following test files has has examples of how to use SEARCH

• test289.js
• test292.js
• test300.js
• test301.js
• test302.js
• test303.js
• test304.js
• test305.js
• test306.js
• test307.js
• test308.js
• test309.js
• test310.js
• test311.js
• test312.js
• test313.js
• test314.js
• test315.js
• test318.js
• test319.js
• test320.js
• test321.js
• test322.js
• test323.js
• test328.js
• test337.js
• test343.js
• test346.js
• test385.js
• test386.js
• test406.js
• test411.js
• test606.js

[AmyBlankenship]

Thanks for this. Do you think it would make it easier for people to know that if the tests had descriptive names and/or were grouped in folders?

[mathiasrw]

The tests are tests. The problem is that the documentation is not good - so thats what we need to fix.

[AmyBlankenship]

I would disagree with that. I'm not familiar with Mocha, so maybe that's just how tests are done in a project that uses it. However, I have never worked on any code where descriptive/expressive file names are considered a bad thing. Even going through the list above you posted, I kept losing my place because test 310 doesn't remind me what the contents are I was just reviewing. And tests are actually documentation as well of the intent of the code (https://www.simple-talk.com/dotnet/net-framework/a-tdd-journey-4-tests-as-documentation-false-positive-results-component-isolation/).

Obviously, it's not my project so I don't want to be one of those people from outside who's just telling people what to do with no understanding or intention of doing anything that helps. But I commonly troll tests for insight into how code can be used that's not provided in the docs. Nobody documents well enough that you can really use their stuff without inspecting some code somewhere.

[mathiasrw]

hmm. Maybe you have a point.

[AmyBlankenship]

Just as a FYI, here is how I used the tests you pointed me to to figure out the correct syntax for my query: http://stackoverflow.com/questions/42708044/alasql-can-you-use-distinct-with-search/42770405#42770405