Documentation for the Midi module

[pitag-ha]

We currently don't have a hygienic structure for cardio-crumble, yet. One thing is that we don't have interface files (i.e. mli-files) for all implementation files (i.e. ml-files). And for the mli-files we have, we don't have documentation.

As a first step to approach this, I propose to add documentation to the midi.mli-file. In OCaml, you mark documentation by (** <your documentation *). You can have a look at the mli-files of, for example, the mirage repo to see some examples for documentation in OCaml.

In general, to write API documentation, one needs to formulate the idea of what the values/types are for, as opposed to putting the implementation of the values/types into words.

[Mojoeffect]

Okay,thanks @pitag-ha
I'll read through that of the mirage repo as you suggested for better understanding.

[AryanGodara]

@pitag-ha Can I work on this alongside #3 (I'll learn about the codebase as I work on both together, and write the docs)

[Mojoeffect]

Hiii @pitag-ha, I'm Joy from Outreachy.
So I'm currently working with VScode text editor to add the documentation.
There are still some Ocaml syntax I'm trying to get familiar with - with the help of a textbook on Ocaml - for efficient documentation of what each value and type that was implemented actually represents.

I've also gone through the mirage repository, where I went through the key.mli file, and the argv.mli to grasp the concept of the documentation.

We currently don't have a hygienic structure for cardio-crumble, yet. One thing is that we don't have interface files (i.e. mli-files) for all implementation files (i.e. ml-files). And for the mli-files we have, we don't have documentation.

As a first step to approach this, I propose to add documentation to the midi.mli-file. In OCaml, you mark documentation by (** <your documentation *). You can have a look at the mli-files of, for example, the mirage repo to see some examples for documentation in OCaml.

In general, to write API documentation, one needs to formulate the idea of what the values/types are for, as opposed to putting the implementation of the values/types into words.

[pitag-ha]

As mentioned in #3, I've just assigned you @Mojoeffect, to this issue, and you, @AryanGodara to #3 to avoid duplicating work.

There are still some Ocaml syntax I'm trying to get familiar with - with the help of a textbook on Ocaml - for efficient documentation of what each value and type that was implemented actually represents.

Sounds great. Don't hesitate to ask if you're stuck with anything!

By the way, if you want, as a first step, you can skip the documentation for module Event and val error_to_string and only write documentation for the rest of Midi for now. Those two items are a bit trickier than the rest.

[kamtoeddy]

Hi @Mojoeffect, please what's the name of the book you are using to study OCaml?

[AryanGodara]

Hi @Mojoeffect, please what's the name of the book you are using to study OCaml?

Hey @kamtoeddy , most people are offline during the weekend I think :D
In the meantime, you can go through these 2 books (really helped me out) :-
OCaml Programming: Correct + Efficient + Beautiful
Real World OCaml 2nd Ed

[Mojoeffect]

Hi @Mojoeffect, please what's the name of the book you are using to study OCaml?

Hey, @kamtoeddy
Well, I started out with
OCaml Programming: Correct + Efficient + Beautiful
In the further reading section of every chapter of that textbook, you'll get access to other documents that will aid the learning process. It's a pretty guided way to learn Ocaml.

[kamtoeddy]

@AryanGodara @Mojoeffect Thanks

[Mojoeffect]

Hiiiiii
So I just opened a PR #11 on this issue, and a review would be appreciated as this is my first attempt at documentation....kinda nervous. Thanks in advance!

[Mojoeffect]

File midi.mli documentation #11

[Mojoeffect]

File midi.mli documentation #11

Hiiii @pitag-ha @Engil
I've made the necessary corrections to the file.
I'd appreciate a feedback/review :) Thanks!