added basic documentation of Prelude module #7
Conversation
There was a problem hiding this comment.
In general this kind of information should be in the source files themselves, so that the documentation can be generated automatically one day. However, since such a tool doesn't exist yet, I'm ok with accepting hand-written docs in case they're helpful to people in the interim.
I don't think the proposed format of the documentation is ideal, mainly because the function signatures are missing. Additionally, none of the definitions exposed by the Prelude and defined in various files in lib/Base are mentioned here (even as uncommented stubs of entries, line near the end of the list in this PR), which may be confusing if someone expects this page to be an exhaustive list of what's provided.
| @@ -1,3 +1,44 @@ | |||
| # Prelude | |||
|
|
|||
| The `Prelude` module is automatically imported and opened in all programs. | |||
|
|
|||
| ### Available functions: | |||
There was a problem hiding this comment.
Why skip a header level like this? Also, the title shouldn't end with ":" and should probably be in title case.
| ### Available functions: | ||
|
|
||
| --- | ||
| `flip f` returns function with flipped arguments |
There was a problem hiding this comment.
I think the documentation would be more usable if each entry started with a codeblock with a particular function's scheme.
The descriptions following that should probably be in the form of sentences, with full stops and capitalization when applicable.
| --- | ||
| `flip f` returns function with flipped arguments | ||
|
|
||
| `flip f x y = f y x` |
There was a problem hiding this comment.
When a paragraph consists of a single piece of inline code then it should probably be a codeblock.
| `flip f x y = f y x` | ||
|
|
||
| --- | ||
| `fst p` returns first element of a pair `p` |
There was a problem hiding this comment.
Many of these descriptions are missing articles, like "the first element".
| `charListToStr xs` converts list of characters `xs` into `String` | ||
|
|
||
| --- | ||
| `chr n` converts integer `n` to corresponding ASCII character (`0 <= n <= 256` to work properly) |
There was a problem hiding this comment.
First of all, typo in the range. Should be n < 256. Second, what happens if it isn't? The bit about "to work properly" is too vague.
No description provided.