search

ocsigen / js_of_ocaml

Compiler from OCaml to Javascript.
http://ocsigen.org/js_of_ocaml/
Other
959 stars 188 forks source link

[Doc] Improve API documentation with small examples #1020

Open olleharstedt opened 4 years ago

olleharstedt commented 4 years ago

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 commented 4 years ago

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 commented 4 years ago

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 commented 4 years ago

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 commented 4 years ago

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

dbuenzli commented 4 years ago

@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 commented 4 years ago

Perfect is the enemy of good...