[Doc] Improve API documentation with small examples

[olleharstedt]

I'd like to supply the API docs with example snippets to show how the module is used. Just reading function listings is not always the best way to learn. Such snippets will have to be maintained, though, so it is a commitment to include it. What do you think?

[TyOverby]

I think that the folks working on mdx have some support for building and running examples in MLI doc-comments. If we could get that working, then maintaining them would be way easier

[dbuenzli]

A simpler approach would be to add the ability to extract code blocks to files in odoc. There's wip by here by @rizo but sadly it seems to have stalled, the discussion got bogged down, in my opinion, into needless complexity.

[olleharstedt]

Hm, not sure why execution would be necessary. The snippets might not be complete anyway. I just thinking more of docblock tags to include code examples.

[olleharstedt]

Something like this: https://github.com/yiisoft/yii2/blob/master/framework/db/ActiveRecord.php#L35

[dbuenzli]

@olleharstedt this already exists. In the ocamldoc language you can write code between {[ ... ]}. The point of extraction is to make sure they compile which help with maintaining them.

[olleharstedt]

Perfect is the enemy of good...