Don't repeat the comments about tablecloth HOT 7 CLOSED

I’m thinking out loud here... In most libraries, there’s a single .mli file, the comments go into it, and some software generates HTML documentation pages from it. I am guessing that some people go straight to the .mli file in the repository rather than the documentation at all.

What we have in tablecloth is a special case (of epic proportions). As you mentioned in #32 (comment), the .mli files are not identical, so there may not be a single source to sync from.

I’m still of the opinion that the best option is to create a new doc subdirectory with the comments in a form that can be used to generate HTML documentation. This is where we would point out how native and BuckleScript differ.

That also means that adding new functions will require changes in three areas: the native .ml/.mli, the BuckleScript .ml/.mli, and the documentation. This is painful for us, but it will be convenient for developers--at least those who can get over the shock of seeing an .mli file without comments in it.

from tablecloth.

Perhaps the library should be written in one style. Then have a build script transform to the other style, and publish it as a separate library. This also makes the namespace not polluted with two different version of each function?

from tablecloth.

This is supported - the docs are generated from a single .mli.

from tablecloth.

One other thought on these lines - the snake_cased versions of the functions often refer to the camelCased version of the function in their comments - this means editor tools that read the comments get the short version for camelCased usages, which is a lot less useful when using the lib than seeing the full comment:

It's be great if the comments could be synced to both versions of the function so you can easily see the doc regardless of which casing you're using.

from tablecloth.

We now share the interface files between implementations, but still need to duplicate the comments between camel and snake functions since, as @actionshrimp pointed out, its not a great experience for people using the snake functions currently.

from tablecloth.

@jfrolich I think it's something we might be able to do with a PPX.

from tablecloth.

Yep. Thats a great idea. Then you also only need the ppx if you need the alternative syntax.

from tablecloth.