Phase 6: Improve documentation

[josephjclark]

OpenMRS docs don't currently give you a lot of help with query APIs:

A couple of comments on this:

• "Sarah" in the example should be in a string. The example is invalid Javascript.
• No query arguments are documented. What shape is thequery object? What do you want from me?
• What does the q query string actually mean? According to the openMRS docs it means "display name of patient" - so we should probably reflect that somewhere.

The wider issue is that each endpoint has a bunch of different query parameters, where q seems pretty common (although maybe with different semantics), and limit is usually accepted I think but even OpenMRS don't document it properly.

The query object provided by our adaptor maps 1:1 with the query parameters in the OpenMRS rest API.

So: I think each operation should have a better, more correct high level explanation, and include a link to the query parameters documented on openMRS. I do not think we should document each parameter on our own docs.

Maybe something like this mock up?

API improvement

I wonder if an improvement on the API would be something like:

searchPatient(name, options, callback)

Where name is the query string (maps toq, and we document that` and, options is an optional list of other parameters. I wonder if that scales nicely across the adaptor

[josephjclark]

Counter point: maybe search needs to be a generic seach, so search(resourceType, query, options), where query changes for each endpoint