search

tjammer / raylib-ocaml

OCaml bindings for raylib and raygui
https://tjammer.github.io/raylib-ocaml/
MIT License
173 stars 14 forks source link

generate docstrings #11

Closed c-cube closed 3 years ago

c-cube commented 3 years ago

I see in raylib_functions.ml that a lot of functions have a comment (extracted from C?) that describes what it does. However it's a (* foo *) comment, and just adding (** foo *) would make merlin/ocamllsp able to show the doc on hover :slightly_smiling_face:

tjammer commented 3 years ago

On the master this is already the case unless I misunderstand your question, see https://github.com/tjammer/raylib-ocaml/blob/5b54051147a718a48bd8b7cf14d466ad15d773e5/src/raylib.mli#L1196 I haven't yet released this version to opam though.

The problem I ran into a lot when using the bindings is that some functions take multiple arguments of the same type and the user might not know which in which. The comments from the C libraries don't help here. For these functions I tried to indicate the usage in the doc comments such as above with init_window, but I did it by hand and surely missed a lot of cases.

Labeled arguments (for these functions) would solve this, but afaik there is no support for them in ctypes and I would need to wrap these functions into labeled versions. One day I will probably go this route.

c-cube commented 3 years ago

Ah, I think raylib.mli is perfect. raylib_functions.ml is where "go to def" took me but it's just implementation details, which makes sense. Thank you!