Start adding doc comments

schala-lang/language/src/lib.rs

@@ -2,6 +2,11 @@
 #![feature(custom_attribute)]
 #![feature(unrestricted_attribute_tokens)]
 #![feature(slice_patterns, box_patterns, box_syntax)]
+
+//! `schala-lang` is where the Schala programming language is actually implemented. 
+//! It defines the `Schala` type, which contains the state for a Schala REPL, and implements
+//! `ProgrammingLanguageInterface` and the chain of compiler passes for it.
+
 extern crate itertools;
 #[macro_use]
 extern crate lazy_static;
@@ -40,6 +45,9 @@ mod eval;
 #[PipelineSteps(tokenizing, parsing(compact,expanded,trace), symbol_table, typechecking, ast_reducing, eval)]
 #[DocMethod = get_doc]
 #[HandleCustomInterpreterDirectives = handle_custom_interpreter_directives]
+/// All bits of state necessary to parse and execute a Schala program are stored in this struct
+/// `state` represents the execution state for the AST-walking interpreter, the other fields
+/// should be self-explanatory.
 pub struct Schala {
   state: eval::State<'static>,
   symbol_table: Rc<RefCell<symbol_table::SymbolTable>>,
@@ -58,6 +66,7 @@ impl Schala {
 }
 
 impl Schala {
+  /// Creates a new Schala environment *without* any prelude.
   fn new_blank_env() -> Schala {
     let symbols = Rc::new(RefCell::new(symbol_table::SymbolTable::new()));
     Schala {
@@ -68,6 +77,8 @@ impl Schala {
     }
   }
 
+  /// Creates a new Schala environment with the standard prelude, which is defined as ordinary
+  /// Schala code in the file `prelude.schala`
   pub fn new() -> Schala {
     let prelude = include_str!("prelude.schala");
     let mut s = Schala::new_blank_env();

schala-lang/language/src/typechecking.rs

@@ -10,6 +10,7 @@ pub struct TypeContext<'a> {
   evar_count: u32
 }
 
+/// `InferResult` is the monad in which type inference takes place.
 type InferResult<T> = Result<T, TypeError>;
 
 #[derive(Debug, Clone)]
@@ -21,6 +22,8 @@ impl TypeError {
   }
 }
 
+/// `Type` is parameterized by whether the type variables can be just universal, or universal or
+/// existential.
 #[derive(Debug, Clone)]
 enum Type<A> {
   Var(A),