documentation

Author: aceinetx

zenlang/src/ast/mod.rs

@@ -1,3 +1,6 @@
+//! ast
+//!
+//! Contains all ast nodes
 pub mod array;
 pub mod array_assign;
 pub mod array_index;

zenlang/src/ast/node.rs

@@ -3,11 +3,23 @@ use alloc::boxed::*;
 use alloc::string::String;
 use alloc::vec::*;
 
+/// Trait implemented by all ast nodes
 pub trait Compile {
+    /// Get the children vector
     fn get_children(&mut self) -> Option<&mut Vec<Box<dyn Compile>>>;
 
+    /// Disable pushing for the current node
+    ///
+    /// This is needed in these cases, where with pushing would just flood the stack with unused data:
+    /// ```
+    /// fn main {
+    ///     123;
+    /// }
+    /// ```
+    /// This would push 123 on the stack with nothing using it, disable_push prevents this
     fn disable_push(&mut self) {}
 
+    /// Compiles the current node and it's children recursively
     fn compile_all(&mut self, compiler: &mut Compiler) -> Result<(), String> {
         if let Err(e) = self.compile(compiler) {
             return Err(e);
@@ -25,5 +37,7 @@ pub trait Compile {
         }
         Ok(())
     }
+
+    /// Compiles the current node
     fn compile(&mut self, compiler: &mut Compiler) -> Result<(), String>;
 }

zenlang/src/compiler.rs

@@ -1,3 +1,7 @@
+//! Compiler
+//!
+//! Compiles ZenLang into a module
+
 use crate::ast::node::Compile;
 use crate::module::Module;
 use crate::parser::*;
@@ -25,10 +29,12 @@ impl<'a> Compiler<'_> {
         return inst;
     }
 
+    /// Get the compile module
     pub fn get_module(&mut self) -> &mut Module {
         return &mut self.module;
     }
 
+    /// Compile everything
     pub fn compile(&mut self) -> Result<(), String> {
         self.warnings.clear();
         if let Err(e) = self.parser.parse() {

zenlang/src/lib.rs

@@ -1,3 +1,12 @@
+//! ZenLang
+//!
+//! Primary programming language of ZenOS
+//! ```
+//! fn main {
+//!     println("Hello from ZenLang");
+//!     return null;
+//! }
+//! ```
 #![no_std]
 pub mod ast;
 pub mod compiler;

zenlang/src/module.rs

@@ -1,3 +1,6 @@
+//! Module
+//!
+//! Contains ZenLang module structs
 use crate::opcode::Opcode;
 use ::serde::{Deserialize, Serialize};
 use alloc::string::String;
@@ -7,10 +10,16 @@ use bincode::config::Configuration;
 use bincode::error::DecodeError;
 use bincode::*;
 
+/// ModuleFunction
+///
+/// Contains information about a module function
 #[derive(Encode, Decode, Serialize, Deserialize, Debug)]
 pub struct ModuleFunction {
+    /// Function name
     pub name: String,
+    /// Function address relative to the module offset
     pub addr: u32,
+    /// Argument count
     pub args_count: u64,
 }
 
@@ -24,9 +33,14 @@ impl ModuleFunction {
     }
 }
 
+/// Module
+///
+/// Contains module information (code)
 #[derive(Encode, Decode, Debug)]
 pub struct Module {
+    /// Opcodes of the module (entire code)
     pub opcodes: Vec<Opcode>,
+    /// Function informations
     pub functions: Vec<ModuleFunction>,
 }
 
@@ -38,12 +52,14 @@ impl Module {
         };
     }
 
+    /// Compiles the module into bytes vector (Serializes)
     pub fn compile(&self) -> Result<Vec<u8>, bincode::error::EncodeError> {
         let cfg = bincode::config::standard();
         let bytes = bincode::encode_to_vec(self, cfg);
         return bytes;
     }
 
+    /// Load the module from bytes vector (Deserializes)
     pub fn load(&mut self, bytes: Vec<u8>) -> Result<(), DecodeError> {
         let cfg = bincode::config::standard();
         match bincode::decode_from_slice::<Module, Configuration>(&bytes, cfg) {
@@ -57,6 +73,7 @@ impl Module {
         }
     }
 
+    /// Get an opcode at a certain address
     pub fn get_opcode(&self, addr: u32) -> &Opcode {
         return &self.opcodes[addr as usize];
     }

zenlang/src/opcode.rs

@@ -1,7 +1,11 @@
+//! Opcode
+//!
+//! What the virtual machine executes
 use alloc::string::*;
 use alloc::vec::*;
 use bincode::*;
 
+/// Opcode
 #[derive(Encode, Decode, Debug)]
 pub enum Opcode {
     Call(),

zenlang/src/parser/mod.rs

@@ -1,3 +1,6 @@
+//! Parser
+//!
+//! Contains a parser for generating AST
 mod parser;
 mod parser_expr;
 mod parser_if_chain;

zenlang/src/parser/parser.rs

@@ -20,6 +20,7 @@ impl<'a> Parser<'_> {
         };
     }
 
+    /// Get the token precedence from a given token
     pub(crate) fn get_token_precedence(&mut self, token: &Token) -> Option<i32> {
         match *token {
             Token::Operator(op) => {
@@ -64,20 +65,30 @@ impl<'a> Parser<'_> {
         }
     }
 
+    /// Steps a token once
+    ///
+    /// Saves the next token to the self.current_token
     pub(crate) fn next(&mut self) -> Token {
         let token = self.tokenizer.next();
         self.current_token = token.clone();
         return token;
     }
 
+    /// Formats an error message like this:
+    ///
+    /// 1: error text
     pub(crate) fn error(&self, text: &str) -> String {
         return format!("{}: {}", self.tokenizer.get_line(), text);
     }
 
+    /// Formats an error message like this:
+    ///
+    /// 1: error text
     pub(crate) fn error_str(&self, text: String) -> String {
         return format!("{}: {}", self.tokenizer.get_line(), text);
     }
 
+    /// Parses a code block
     pub(crate) fn parse_block(&mut self) -> Result<Vec<Box<dyn node::Compile>>, String> {
         let mut vec: Vec<Box<dyn node::Compile>> = Vec::new();
 
@@ -104,6 +115,7 @@ impl<'a> Parser<'_> {
         Ok(vec)
     }
 
+    /// Parses function
     pub(crate) fn parse_function(&mut self) -> Result<(), String> {
         let token = self.next();
         if let Token::Identifier(name) = token {
@@ -141,6 +153,7 @@ impl<'a> Parser<'_> {
         Ok(())
     }
 
+    /// Parse everything to self.root
     pub fn parse(&mut self) -> Result<(), String> {
         self.root = root::AstRoot::new();
 

zenlang/src/parser/parser_expr.rs

@@ -6,6 +6,10 @@ use alloc::format;
 use alloc::string::*;
 
 impl<'a> Parser<'_> {
+    /// Parses an expression
+    ///
+    /// * `min_prec` - Minimal precedence, 0 if just started parsing
+    /// * `step_token` - Whether parse_expression should step a token once
     pub(crate) fn parse_expression(
         &mut self,
         min_prec: i32,

zenlang/src/parser/parser_if_chain.rs

@@ -5,6 +5,7 @@ use alloc::boxed::*;
 use alloc::string::*;
 
 impl<'a> Parser<'_> {
+    /// Parses an if chain
     pub(crate) fn parse_if_chain(&mut self) -> Result<Box<dyn node::Compile>, String> {
         let mut chain = if_chain::AstIfChain::new();
         loop {