As we get ready to release Attachment Converter, we need to start documenting the code in more detail. The first step of that is:
creating interface files for all modules in the project
writing docstrings for all values those interface files expose
One of the ways we've customarily cut corners in the DLDC is to skip defining .mli files for our projects, which means this will be kind of a new endeavor for us. That said, we can recommend the following general approach, for each of the module files in the project:
generate an initial .mli file using the ocaml-print-intf utility
comment the whole thing out
see what compiler errors result from the interface exposing nothing
uncomment the value the compiler complains isn't in scope
rinse and repeat
Once we have used this technique to identify the minimal set of values that each module needs to expose, we can set about writing docstrings for those values, which are what will go into our auto-generated odoc documentation.
As we get ready to release Attachment Converter, we need to start documenting the code in more detail. The first step of that is:
One of the ways we've customarily cut corners in the DLDC is to skip defining
.mlifiles for our projects, which means this will be kind of a new endeavor for us. That said, we can recommend the following general approach, for each of the module files in the project:.mlifile using theocaml-print-intfutilityOnce we have used this technique to identify the minimal set of values that each module needs to expose, we can set about writing docstrings for those values, which are what will go into our auto-generated
odocdocumentation.For more info on the syntax of
odoc's markup language, please see: https://ocaml.github.io/odoc/odoc_for_authors.html