search

restjquery / RESTjQuery

Handle REST-API requests from or to your WordPress site using jQuery.
https://restjquery.com
22 stars 7 forks source link

Documentation improvements #3

Open nylen opened 7 years ago

nylen commented 7 years ago

For example:

seb86 commented 7 years ago

Documentation will be provided once the script is complete. Code is not finalised at this time.

nylen commented 7 years ago

This sounds like a good idea to avoid duplicating work, but in practice this usually leads to documentation never being written. Also, code is never "complete", and the process of writing documentation often informs design improvements. (Similarly with unit tests, but that is another topic.)

seb86 commented 7 years ago

After the next update I will start writing docmentation. Most likely only be for GET requests until authentication is figured out.

seb86 commented 7 years ago

I have started to write the documentation using Slate. Nothing much at the moment. Just getting the structure ready.

https://seb86.github.io/WordPress-REST-API-jQuery-Documentation/

nylen commented 7 years ago

I think this project is small enough that the documentation could just live in the readme. In any case you want to avoid duplicating information. If you're using slate I guess you could replace the readme with a few sentences + a link to the documentation site? Though my opinion is still that it's not worth making users go to another site for documentation.

It's still not clear how to receive the results of an API call. Does restjQuery accept a callback function? Return a promise? This should be documented and indicated in the examples.

seb86 commented 7 years ago

I will provide clear examples soon.

nylen commented 7 years ago

When I make a call to an endpoint, how do I get the results?

I found the answer to this in the code rather than the documentation: this library uses async: false, so when a request is made, the data is returned immediately.

You should change this as soon as possible to use promises and/or callbacks. Here's why:

Synchronous XMLHttpRequest outside of workers is in the process of being removed from the web platform as it has detrimental effects to the end user’s experience. (This is a long process that takes many years.) Developers must not pass false for the async argument when current global object is a Window object. User agents are strongly encouraged to warn about such usage in developer tools and may experiment with throwing an InvalidAccessError exception when it occurs.

seb86 commented 7 years ago

Yes I have been reading these types of topics to improve the library. I have little time at the moment to apply these improvements but will try to get it done soon. I am in the middle of writing the documentation currently.