Add missing API documentation

[grabbou]

Describe Container and Link props and behavior

[yawaramin]

I recommend creating a ReRoute.rei file and putting the interfaces as well as doc comments there. A good interface file is invaluable as documentation. It would look something like this:

/** ReRoute - a fast, declarative micro-router for React. Create a router
    by passing in a configuration. */

module type RouterConfig = {...};
module type Container = {...};
module type Link = {...};

/** [CreateRouter(Config)] returns a new router module created from
    [Config]. You'll need to create the [Config] beforehand to be able to
    access its contents later. */
module CreateRouter: RouterConfig => {
  /** The wrapper component that renders the individual paths and routes
      to them. */
  module Container: Container;

  /** ... */
  module Link: Link;
};

We badly need a good documentation tool for Reason, but in the interim I think doc comments are the best, future-proof, option we have.

[grabbou]

Thanks for chiming in! That sounds like a good improvement. Do you have a link that explains a bit more about rei files? I've found them quite a few times already across different codebases and been wondering what is its purpose.

We badly need a good documentation tool for Reason

Is there any RFC / work in progress in that regards that I can follow?

[yawaramin]

Yeah, they're a bit of a hidden gem of Reason, there's a little more documentation here https://reasonml.github.io/docs/en/module.html#signatures

I haven't heard of too much progress on documentation unfortunately. There is the existing ocamldoc tool but it works only with OCaml syntax, and it's not super easy to set up, see e.g. https://github.com/yawaramin/bs-webapi/blob/79dedbda2f2a27f596bb801dd4f5491e05b2138b/package.json#L8

We'll need to come up with a better doc story pretty soon in the community.