Grand Documentation Plan [WIP]

[cuihtlauac]

In this discussion, “documentation” means stuff in ocaml.org/docs, not package documentation.

Where we are

When not a university student attending an OCaml course, it's perceived as difficult to learn OCaml. The highest quality materials currently available are:

• Real World OCaml. An excellent book, however:

  • It's using https://opensource.janestreet.com/base, which is an awesome library but is not vanilla OCaml
  • It's a book. Books are great for book readers, no so much for those who aren't

• Lectures notes from Cambridge and Cornell

  • https://www.cl.cam.ac.uk/teaching/1920/cst/node9.html
  • https://cs3110.github.io/textbook

None of those materials is suitable for online self-training.

Some topics are covered in ocaml.org/docs, but many topics are missing.

References

1. https://counterexamples.org/

Where we'd like to go

TODO: {0,1} to {0,1} correspondence with existing docs

1. Language Concepts
   1. Types
      1. Records
      2. Constructors & Variants
      3. Generalized Algebraic Data Types (GADT)
      4. Polymorphic Variants
      5. Primitive Types
      6. Unit & Empty
      7. Abstract Types
   2. Syntax
      1. Infix Operators
      2. Let Bindings
      3. List Concatenationn
      4. List Insertion
      5. Boolean Operators
   3. Object
      1. Classes
      2. Inheritance
   4. Conditions
   5. Loops
      1. For Loops
      2. While Loops
   6. Mutability
      1. Mutable Fields
      2. References
      3. Mutable Structures
      4. For Loop
   7. Packages
      1. Library
      2. Executable
      3. Dependencies
      4. Package Management
      5. opam-repository
   8. Effects and Purity
      1. Referential Transparency
      2. Exceptions
      3. Effect System
      4. Haskell-like IO Monad
   9. Functions
      1. Applying a function
      2. Anonymous functions
      3. Programs
      4. Recursivity & Tail-Recursion
      5. Currying
      6. Scope
      7. Unlabelled & Labeled Arguments
      8. Optional Arguments
   10. Data Structures
       1. Tuples
       2. Arrays
       3. Maps
       4. Lists
       5. Sequences (not to be confused with streams)
       6. Sets
       7. Hash Tables
   11. Memoization
   12. Hash-consing
   13. Programs
       1. Where is main?
       2. Native vs Bytecode Programs
   14. Pattern Matching
       1. match ... with, function and irrefutable patterns
       2. Extract a list
       3. Performance Considerations
   15. Monads
       1. Monoid
       2. Applicative
       3. Infix Operators and Customs Bindings
   16. Concurrent Programming
       1. Domains
       2. Effects
       3. Processes
       4. Eio
   17. Modules & Functors
       1. Module vs Classes
       2. Linking
       3. Module
       4. Functors
       5. Module Types
       6. open and include
       7. Recursive Module
       8. type t
       9. Contravariance
   18. Promises
   19. Type Inference
       1. Type Constraints
   20. Error Handling
       1. Exceptions
       2. Result
       3. Option
       4. Assertions
   21. Misc
       1. Obj.magic
       2. /2 in types
       3. Type Inference Algorithmic Complexity
       4. Type Soundness
2. Tooling
   1. Getting started
      1. Why OCaml -- https://ocaml.org/about
      2. OCaml Platform
      3. Installing OCaml
      4. Editor Setup
         1. Vi/Vim
         2. Emacs
         3. VSCode
         4. LSP
         5. Merlin
      5. Utop, REPL & Playground
      6. Community Overview
   2. Workflows
      1. Creating a project
      2. Compiling and Running
      3. Installing Dependencies
      4. Unit Testing
      5. Publishing
      6. Debugging -- https://ocaml.org/docs/debugging
   3. Common Errors -- https://ocaml.org/docs/common-errors
      1. Type Mismatches
      2. Type Definition Mismatches
      3. Cyclic Dependencies
      4. Missing Definition
   4. Resources
      1. Operator Index
      2. Terminology
      3. Conventions
         1. Small close or match of if-then-else on top
         2. Modules and Function Names -- https://ocaml.org/docs/modules
         3. No abbreviations
      4. Syntax Cheatsheet
         1. Equivalent in Other Languages
         2. Links to Documentation
      5. Theory
         1. Big-Oh Notation
         2. Type Theory
         3. Monads
         4. Category Theory
      6. Ocaml Platform
   5. Tutorials
      1. Lwt
      2. Interfacing with C -- https://ocaml.org/docs/calling-c-libraries
      3. Command line arguments -- https://ocaml.org/docs/cli-arguments
      4. S-Expression
      5. Lexing and Parsing
   6. Advanced Topics
      1. Generalized Algebraic Datatypes
      2. Foreign Function Interface
      3. Memory Layout
      4. Garbage Collection -- https://ocaml.org/docs/garbage-collection
      5. Exceptions Internals
      6. Language Implementation
      7. Syntactic Diagrams
      8. Performance Profiling -- https://ocaml.org/docs/profiling
      9. Compiler Toolchain
      10. Pointers -- https://ocaml.org/docs/pointers
      11. Metaprogramming -- https://ocaml.org/docs/metaprogramming
      12. System Programming
      13. Obj.magic
   7. Trivia
      1. History, from CAM to OCaml
      2. Hall of Fame
      3. Anecdotes and Jokes
3. Unclassfied
   1. https://ocaml.org/docs/lists
   2. https://ocaml.org/docs/map
   3. https://ocaml.org/docs/sets
   4. https://ocaml.org/docs/hash-tables
   5. https://ocaml.org/docs/data-structures-comparison
   6. https://ocaml.org/docs/up-and-running
   7. https://ocaml.org/docs/first-hour
   8. https://ocaml.org/docs/ocaml-on-windows
   9. https://ocaml.org/docs/data-types
   10. https://ocaml.org/docs/functional-programming
   11. https://ocaml.org/docs/if-statements-and-loops
   12. https://ocaml.org/docs/labels
   13. https://ocaml.org/docs/functors
   14. https://ocaml.org/docs/objects
   15. https://ocaml.org/docs/error-handling
   16. https://ocaml.org/docs/guidelines
   17. https://ocaml.org/docs/formatting-text
   18. https://ocaml.org/docs/file-manipulation
   19. https://ocaml.org/docs/calling-fortran-libraries
   20. https://ocaml.org/docs/compiling-ocaml-projects
   21. https://ocaml.org/docs/best-practices