Tutorials: Make references to previously defined functions future-proof
pitag-ha opened this issue · 7 comments
(1) At the beginning of the the "A first hour with OCaml" tutorial, the function average is defined:
# let average a b =
(a +. b) /. 2.0;;
val average : float -> float -> float = <fun>
(2) Later on, it's signature is pointed out separately:
average : float -> float -> float
That signature is hard-coded, which is not future-proof: if at some point one was to change or even remove (1), then (2) would be out of context.
I suggest to make it future-proof by tying (2) to (1).
@johnwhitington, does this sound good to you? :) If not, we'll close it before someone starts working on it.
Do you mean that you intend to have a mechanism in the HTML which pulls out the type from the generated example, and substitutes the text in (2)?
That would be one good possibility, yes. Another option would be to use the toplevel in (2). I've left the approach a bit open.
The HTML file is generated automatically from the .md file in site/learn/tutorial/, so I don't see how this is achieved...
Would the toplevel approach be an option for you?
Can you explain it to me?
Yes, you're right, I should be more concrete here! I was thinking about writing average (and the other function) into an ocamltop block. But I'll close this, since I was looking for a medium issue for Outreachy applicants and given that one approach isn't possible and the other approach is pretty simple once discussed (and controversial), this isn't a good medium issue. Thanks for your fast reply and help :)