Document SDK methods (not wrapping API routes) properly

[eskombro]

CONTEXT

• We haven't implemented SDK individual documentation (which will probably take some time)
• We are removing the examples section in the README.md for each SDK

ISSUE

Methods implemented by the SDKs are not documented anywhere at this moment. The only way a user can learn about these methods (waitForPendingUpdate, getOrCreateIndex, ...) is going through the source code, reading the methods or tests.

SOLUTION

Those methods that are implemented (or supposed to be implemented) in every SDK should be documented somewhere, not only so the user can understand how they work, but even to let him discover them. There are two main possibilities:

Option 1

In the docs, we have a dedicated page for SDKs. We can document those methods there once, and add samples for each language.

Option 2

In every readme, we can explain them and give an exmaple

Option 3 (1 + 2)

We document them in the official docs, and in every readme we write a sentence saying that those methods exist, and redirect the user to the official docs.

I would like to have your opinion on this! Thanks!

[tpayet]

I am really afraid of having too many parts of documentation to maintain with option 1 or 3.
As a Ruby and Python developer, I am not afraid of going through the source code or using the REPL to understand which methods are available (as long as they are intuitive methods).

Maybe should we remove example from README only when the methods are documented in the documentation of MeiliSearch and then could we add a Higher level methods not documented in documentation part in each sdk readme?

[curquiza]

I agree with @tpayet: I would rather have a section in the SDK READMEs since these methods are not really related to MeiliSearch (the core-engine) and really specific to the SDK: some of them are not implemented in all the SDKs, or could be useful for an SDK but not for another... etc
That's why I would rather not have these methods in the main docs.
What do you think @bidoubiwa?

[bidoubiwa]

Option 2 is the best solution for the moment.
Later on we could consider adding the following to the documentation

• API references > SDK utilities (or ressources instead of API references)

We will need sooner or later a complete documentation for the front-end implementation of MeiliSearch. For which I would make a category in the documentation.

[curquiza]

So, let's start with documentation in the README as a first step! We will open a new issue in this repo and in the documentation repo when needed 😉

I pass this issue as ready to implement and I suggest that someone does directly a PR on a chosen repo as a first version so that we can review it easily 🙂

[brunoocasali]

Closed in favor of the new tracking issue for this subject #201.