kobotoolbox: functions documentation & examples

[aleksa-krolls]

Review & audit the existing docs for the Kobo adaptor to determine what the "best-class" version of the documentation on the adaptor functions and examples could look like.

To check:

• [ ] does an example exist for each function?
• [ ] are options documented? (And how do we do this?)
• [ ] are API limits documented? (And how do we do this?)
• [ ] is the configuration schema (and optional parameters) clearly documented?

[josephjclark]

Here is my feedback for the API reference.

I am going to make a few comments on the API itself while I'm here, although that's technically not part of this work

tl;dr

• need typedefs for params
• Would benefit from a few more examples
• No docs at all on state transformation

General

• There is no mention of API limits and/or paging. I don't know if either are relevant
• In this API, the params object feels more like options, and I would be in favour of changing the APIs to be a bit cleaner
• The docs are very brief and the semantics of it are generally very loose, making a small and simple API hard to understand and work with
• At least the signatures are nice and consistent with a (params, callback) structure

getDeploymentInfo

• params are not documented in detail (needs a typedef)
• params language is vague - it talks about a fetch or filter but neither thing is explained
• Also it says "a specific form" but if I don't pass a form id or filter, will it return all forms?
• callback function is not well described (to be fair, it never is). It's actually an operation signature.
• No documentation on the returned/transformed state
• There is one decent example, although I'm not a great fan of using the callback to log
• I'd like to see three examples: get info for a form, get with filter, and get with callback.
• There is no direct mapping to the kobotoolbox API or docs (again, this is a general problem across our docs)
• API note: I think the signature should be getDeploymentInfo(formId, options, callback)

getForms

• Is this a HTTP function or a high level helper? It mixes metaphors. It talks about making a request an says you can attach headers etc. But as it's called getForms it should really be abstracting out the HTTP API.
• params is not documented
• Make a request to get the list of forms - what forms? All forms? Can I filter?
• API note: is this any different from getDeploymentInfo?
• No docs on state transformation - what does my returned state.data look like? What does this actually get?
• There's one example which uses an empty object for params (not nice), and has a console.log callback (not a fan). I prefer to see get all forms as one example, and maybe get with callback as another. If those params are actually important (and I doubt it) we should add an example for them too

getSummissions

• Same feedback as getDeployment info really
• Get submissions for a specific form but params says it allows a filter? So is it for one form or can I get all submissions and filter?

[josephjclark]

There is clear documentation on the configuration. Like every other adaptor I don't think its well presented, but that's a wider problem

[josephjclark]

There is one example, with a score of 0, with no code. So that needs sorting out.

Also the readme has quite a nice example of filtering on submissions