Manifest design of the Standard Library in its README

Author: ssoelvsten

lib/README.md

@@ -21,13 +21,19 @@ reviewed rigorously rather than depend on the monitor.
 To compile a module as part of the standard library, add it to the list of files in the `lib`
 target of the *makefile*.
 
+## Design Principles
+
+- File names are written in `CamelCase`. This makes them conform to the Standard ML Basis Library.
+- It is more important to match the function names and signatures in the Standard ML library than to
+  improve on them. For example, `String.sub` would make more sense with the type `[Char] -> Int ->
+  Char` but to match the SML library, we will stick with `[Char] * Int -> Char`.
+- Each module exports a single *record* with the same name as the file. This (1) makes it closer to
+  the SML module system and (2) allows for name resolution, e.g. `HashMap.findOpt` and
+  `ListPair.findOpt` can be used in the same file.
+- Each function that is exported has to be documented (`(** <text> *)`). In the long run, we will
+  auto-generate documentation for the Standard Library.
+
 ## TODO
 
-- To conform with the Standard ML Basis Library, we should have the files conform to a `CamelCase`
-  style.
-- To fake namespaced import, e.g. `List.length`, the library should export a struct instead. Only
-  certain functions should "pollute" the global namespace.
-- Quite a lot of the standard library is not documented in any way. What is the purpose of each
-  function and each module? The [modules](#modules) above are the ones that have been updated and
-  documented.
-- There are a lot of things in here - some of it dead. Can we merge/remove some things?
+The [modules](#modules) mentioned above already follow the [design principles](#design-principles).
+The remaining files either need to be updated or to be removed.