Merge branch 'gardening/code-comments' into 'dev'

[LIGO-114] Add comments to various files in the source tree

See merge request ligolang/ligo!117

src/passes/1-parser/pascaligo.mli

@@ -0,0 +1,21 @@
+(* This file provides an interface to the PascaLIGO parser. *)
+
+open Trace
+
+module Parser = Parser_pascaligo.Parser
+module AST = Parser_pascaligo.AST
+module ParserLog = Parser_pascaligo.ParserLog
+module LexToken = Parser_pascaligo.LexToken
+
+
+(** Open a PascaLIGO filename given by string and convert into an abstract syntax tree. *)
+val parse_file : string -> (AST.t result)
+
+(** Convert a given string into a PascaLIGO abstract syntax tree *)
+val parse_string : string -> AST.t result
+
+(** Parse a given string as a PascaLIGO expression and return an expression AST.
+
+This is intended to be used for interactive interpreters, or other scenarios 
+where you would want to parse a PascaLIGO expression outside of a contract. *)
+val parse_expression : string -> AST.expr result

src/passes/1-parser/pascaligo/AST.mli

@@ -135,8 +135,15 @@ type 'a braces = {
   rbrace : rbrace
 }
 
-(* The Abstract Syntax Tree *)
+(** The Abstract Syntax Tree 
 
+The AST mirrors the contents of Parser.mly, which defines a tree of parsing
+productions that are used to make a syntax tree from a given program input.
+
+This file defines the concrete AST for PascaLIGO, which is used to associate
+regions of the source code text with the contents of the syntax tree.
+
+*)
 type t = {
   decl : declaration nseq;
   eof  : eof

src/passes/1-parser/pascaligo/LexToken.mli

@@ -1,4 +1,4 @@
-(* This signature defines the lexical tokens for LIGO
+(** This signature defines the lexical tokens for LIGO
 
    _Tokens_ are the abstract units which are used by the parser to
    build the abstract syntax tree (AST), in other words, the stream of

src/passes/1-parser/shared/Markup.mli

@@ -1,12 +1,11 @@
-(* This module defines the sorts of markup recognised by the LIGO
+(** This module defines the sorts of markup recognised by the LIGO
    lexer *)
 
 module Region = Simple_utils.Region
 
-(* A lexeme is piece of concrete syntax belonging to a token. In
+(** A lexeme is piece of concrete syntax belonging to a token. In
    algebraic terms, a token is also a piece of abstract lexical
    syntax. Lexical units emcompass both markup and lexemes. *)
-
 type lexeme = string
 
 type t =
@@ -19,7 +18,7 @@ type t =
 
 type markup = t
 
-(* Pretty-printing of markup
+(** Pretty-printing of markup
 
    The difference between [to_lexeme] and [to_string] is that the
    former builds the corresponding concrete syntax (the lexeme),

src/passes/2-simplify/pascaligo.ml

@@ -8,7 +8,6 @@ open Combinators
 
 let nseq_to_list (hd, tl) = hd :: tl
 let npseq_to_list (hd, tl) = hd :: (List.map snd tl)
-let npseq_to_nelist (hd, tl) = hd, (List.map snd tl)
 let pseq_to_list = function
   | None -> []
   | Some lst -> npseq_to_list lst

src/passes/2-simplify/pascaligo.mli

@@ -1,81 +1,26 @@
+(** Converts PascaLIGO programs to the Simplified Abstract Syntax Tree. *)
+
 open Trace
 open Ast_simplified
 
 module Raw = Parser.Pascaligo.AST
 module SMap = Map.String
 
-(*
-val nseq_to_list : 'a * 'a list -> 'a list
-val npseq_to_list : 'a * ( 'b * 'a ) list -> 'a list
-*)
-val npseq_to_nelist : 'a * ( 'b * 'c ) list -> 'a * 'c list
-(*
-val pseq_to_list : ('a * ('b * 'a) list) option -> 'a list
-val get_value : 'a Raw.reg -> 'a
-*)
-
 module Errors : sig
-  (*
+
-  val unsupported_cst_constr : Raw.pattern -> unit -> error
-  val unsupported_ass_None : Raw.wild -> unit -> error
-  val unsupported_entry_decl : 'a Raw.reg -> unit -> error
-  val unsupported_proc_decl : 'a Raw.reg -> unit -> error
-  *)
   val bad_bytes : Location.t -> string -> unit -> error
-  (*
+
-  val unsupported_local_proc : Raw.wild -> unit -> error
-  val corner_case : loc:string -> string -> unit -> error
-  val unknown_predefined_type : string Raw.reg -> unit -> error
-  *)
   val unsupported_arith_op : Raw.expr -> unit -> error
-  (*
+
-  val unsupported_set_expr : Raw.expr -> unit -> error
-  *)
   val unsupported_proc_calls : 'a Raw.reg -> unit -> error
-  (*
+
-  val unsupported_for_loops : Raw.wild -> unit -> error
-  val unsupported_deep_map_assign : 'a Raw.reg -> unit -> error
-  val unsupported_empty_record_patch : 'a Raw.reg -> unit -> error
-  val unsupported_map_patches : 'a Raw.reg -> unit -> error
-  val unsupported_set_patches : 'a Raw.reg -> unit -> error
-  val unsupported_deep_map_rm : 'a Raw.reg -> unit -> error
-  val unsupported_set_removal : 'a Raw.reg -> unit -> error
-  val unsupported_non_var_pattern : Raw.pattern -> unit -> error
-  val only_constructors : Raw.pattern -> unit -> error
-  val unsupported_tuple_pattern : Raw.pattern -> unit -> error
-  val unsupported_deep_Some_patterns : Raw.pattern -> unit -> error
-  val unsupported_deep_list_patterns : 'a Raw.reg -> unit -> error
-  val unsupported_sub_blocks : 'a Raw.reg -> unit -> error
-  val simplifying_instruction : Raw.instruction -> unit -> error
-  *)
 end
 
-(*
+
-val r_split : 'a Raw.reg -> 'a * Location.t
+(** Convert a concrete PascaLIGO expression AST to the simplified expression AST 
-val return : expr -> ( expr option -> expr result ) result
+    used by the compiler. *)
-val return_let_in : ?loc:Location.t -> string * type_expression option -> expr -> ( expr option -> expr result ) result
-val simpl_type_expression : Raw.type_expr -> type_expression result
-val simpl_list_type_expression : Raw.type_expr list -> type_expression result
-*)
 val simpl_expression : Raw.expr -> expr result
-(*
+
-val simpl_logic_expression : Raw.logic_expr -> expression result
+(** Convert a concrete PascaLIGO program AST to the simplified program AST used 
-val simpl_list_expression : Raw.list_expr -> expression result
+    by the compiler. *)
-val simpl_set_expression : Raw.set_expr -> expression result
-val simpl_binop : string -> Raw.wild Raw.bin_op Region.reg -> expression result
-val simpl_unop : string -> Raw.wild Raw.un_op Region.reg -> expression result
-val simpl_tuple_expression : ?loc:Location.t -> Raw.expr list -> expression result
-val simpl_local_declaration : Raw.local_decl -> ( expr option -> expr result) result
-val simpl_data_declaration : Raw.data_decl -> ( expr option -> expr result ) result
-val simpl_param : Raw.param_decl -> (type_name * type_expression) result
-val simpl_fun_declaration : loc:Location.t -> Raw.fun_decl -> ((name * type_expression option) * expression) result
-val simpl_declaration : Raw.declaration -> declaration Location.wrap result
-val simpl_single_instruction : Raw.single_instr -> (expression option -> expression result) result
-val simpl_path : Raw.path -> string * Ast_simplified.access_path
-val simpl_cases : (Raw.pattern * 'a) list -> 'a matching result
-val simpl_instruction_block : Raw.instruction -> (expression option -> expression result) result
-val simpl_instruction : Raw.instruction -> (expression option -> expression result) result
-val simpl_statements : Raw.statements -> (expression option -> expression result) result
-val simpl_block : Raw.block -> (expression option -> expression result) result
-*)
 val simpl_program : Raw.ast -> program result

src/passes/6-transpiler/transpiler.ml

@@ -1,3 +1,7 @@
+(* The Transpiler is a function that takes as input the Typed AST, and outputs expressions in a language that is basically a Michelson with named variables and first-class-environments.
+
+For more info, see back-end.md: https://gitlab.com/ligolang/ligo/blob/dev/gitlab-pages/docs/contributors/big-picture/back-end.md *)
+
 open! Trace
 open Helpers
 

src/stages/ast_simplified/PP.mli

@@ -1,3 +1,5 @@
+(** Pretty printer for the Simplified Abstract Syntax Tree *)
+
 open Types
 open Format
 
@@ -32,7 +34,7 @@ val matching_variant_case : (formatter -> 'a -> unit) -> formatter -> (construct
 val matching : (formatter -> 'a -> unit) -> formatter -> 'a matching -> unit
 *)
 
-(* Shows the type expected for the matched value *)
+(** Shows the type expected for the matched value *)
 val matching_type : formatter -> 'a matching -> unit
 
 (*
@@ -41,4 +43,5 @@ val matching_variant_case_type : formatter -> ( ( constructor_name * name) * 'a)
 val declaration : formatter -> declaration -> unit
 
 *)
+(** Pretty print a full program AST *)
 val program : formatter -> program -> unit