Added documentation that can be picked up by Haddock

Author: Louis Jenkins

.gitignore

@@ -0,0 +1 @@
+Documentation/

VirtualMachine/ByteCode.hs

@@ -21,7 +21,7 @@ module VirtualMachine.ByteCode where
         8 -> readIORef (current_class env) >>= \c -> (return . VString . show . utf8_bytes) (constant_pool c !! (fromIntegral . string_index $ info))
         _ -> error $ "Bad Tag: " ++ show (tag info)
 
-  {- Starting point of execution of ByteCode isntructions -}
+  {- | Starting point of execution of ByteCode isntructions -}
   execute :: Runtime_Environment -> IO ()
   execute env = head <$> readIORef (stack env)  -- Take the head of the stack (current stack frame)
     >>= \frame -> when (debug_mode env) (debugFrame frame >>= putStrLn) -- Optional Debug
@@ -91,7 +91,7 @@ module VirtualMachine.ByteCode where
             utf8_name = cpool !! fromIntegral (name_index name_and_type)
             in show . utf8_bytes $ utf8_name
 
-  {- Loads from local_variables to operand_stack -}
+  {- | Loads from local_variables to operand_stack -}
   loadOp :: StackFrame -> ByteCode -> IO ()
   loadOp frame bc
     -- Loads with the index as the next bytecode instruction
@@ -100,7 +100,7 @@ module VirtualMachine.ByteCode where
     | bc >= 26 && bc <= 45 = getLocal' frame ((bc - 26) `mod` 4) >>= pushOp frame
     | otherwise = error $ "Bad ByteCode Instruction: " ++ show bc
 
-  {- Stores from operand_stack to local_variables -}
+  {- | Stores from operand_stack to local_variables -}
   storeOp :: StackFrame -> ByteCode -> IO ()
   storeOp frame bc
     -- Stores with the index as the next bytecode instruction
@@ -118,7 +118,7 @@ module VirtualMachine.ByteCode where
     | otherwise = error $ "Bad ByteCode Instruction: " ++ show bc
 
 
-  {- Stores constant values on the Operand Stack. -}
+  {- | Stores constant values on the Operand Stack. -}
   constOp :: StackFrame -> ByteCode -> IO ()
   constOp frame bc
     -- Null Reference
@@ -134,7 +134,7 @@ module VirtualMachine.ByteCode where
     -- ERROR
     | otherwise = error $ "Bad ByteCode Instruction: " ++ show bc
 
-  {- Math operations which are abstracted by the Value type. -}
+  {- | Math operations which are abstracted by the Value type. -}
   mathOp :: StackFrame -> ByteCode -> IO ()
   mathOp frame bc
     | bc >= 96 && bc <= 99 = applyBinaryOp (+)
@@ -160,7 +160,7 @@ module VirtualMachine.ByteCode where
         increment = -- 'iinc' has local variable index as first, with value as second indice
           join $ modifyLocal frame <$> getNextBC frame <*> ((+) . fromIntegral <$> getNextBC frame)
 
-  {- Conditional jump instructions ('if', 'for', and 'while') -}
+  {- | Conditional jump instructions ('if', 'for', and 'while') -}
   cmpOp :: StackFrame -> ByteCode -> IO ()
   cmpOp frame bc
     | bc >= 148 && bc <= 152 = pushCmp
@@ -199,15 +199,15 @@ module VirtualMachine.ByteCode where
         -1 -> LT
         _ -> error "Bad Enumerable Value! "
 
-  {- Obtains the next ByteCode instruction and increments the PC -}
+  {- | Obtains the next ByteCode instruction and increments the PC -}
   getNextBC :: StackFrame -> IO ByteCode
   getNextBC frame = readIORef frame >>= \f -> -- Read StackFrame from passed reference
     let segment = code_segment f in -- Retrieve current set of instructions
     readIORef (program_counter segment) >>= \n -> -- Read current ByteCode instruction
     modifyIORef (program_counter segment) (+1) >> -- Increment PC
     return (byte_code segment !! fromIntegral n) -- Return ByteCode instruction
 
-  {- Obtains the next two ByteCode instructions as a short, and increments the PC by 2 -}
+  {- | Obtains the next two ByteCode instructions as a short, and increments the PC by 2 -}
   getNextShort :: StackFrame -> IO Word16
   getNextShort frame = replicateM 2 (getNextBC frame) >>= \(i1:i2:_) ->
     return $ fromIntegral i1 `shift` 8 .|. fromIntegral i2

VirtualMachine/Environment.hs

@@ -8,14 +8,14 @@ module VirtualMachine.Environment where
   import VirtualMachine.ByteCode
   import Data.Maybe
 
-  {- Starting point for the runtime, invoked to instantiate the runtime environment -}
+  {- | Starting point for the runtime, invoked to instantiate the runtime environment -}
   init :: Bool -> IO Runtime_Environment
   init debug = Environment <$> newIORef undefined -- 'current_class' is not available yet
     <*> newIORef Map.empty -- 'class_map' is originally empty
     <*> newIORef []  -- The 'stack' is initially empty
     <*> return debug -- 'debug' is used for conditional logging
 
-  {- Minimal bootstrap class loader -}
+  {- | Minimal bootstrap class loader -}
   loadClass :: Runtime_Environment -> ClassFile -> IO ()
   loadClass env cf =
     toClass cf >>= \c -> modifyIORef' (class_map env) (Map.insert classString c)
@@ -28,7 +28,7 @@ module VirtualMachine.Environment where
           name = cp !! fromIntegral (name_index class_info)
           in show $ utf8_bytes name
 
-  {- Primer for the runtime, which sets up and executes the 'main' method -}
+  {- | Primer for the runtime, which sets up and executes the 'main' method -}
   start :: Runtime_Environment -> IO ()
   start env = (fromJust . Map.lookup "main") <$> -- Look for "main" function (result is a pair)
     ((snd . head . Map.toList) <$> -- Take the first (only) result and the second of pair (class)

VirtualMachine/Stack.hs

@@ -6,14 +6,14 @@ module VirtualMachine.Stack where
   import VirtualMachine.Stack_Frame
   import VirtualMachine.ByteCode
 
-  {- Obtains the current stack frame -}
+  {- | Obtains the current stack frame -}
   getCurrentFrame :: Runtime_Environment -> IO StackFrame
   getCurrentFrame env = head <$> readIORef (stack env)
 
-  {- Pops the current stack frame off of the stack -}
+  {- | Pops the current stack frame off of the stack -}
   popFrame :: Runtime_Environment -> IO ()
   popFrame env = modifyIORef' (stack env) tail
 
-  {- Create a frame for the passed method and pushes on stack -}
+  {- | Create a frame for the passed method and pushes on stack -}
   pushFrame :: Runtime_Environment -> Method -> IO ()
   pushFrame env meth = createFrame meth >>= \f -> modifyIORef (stack env) ((:) f)

VirtualMachine/Stack_Frame.hs

@@ -6,7 +6,7 @@ module VirtualMachine.Stack_Frame where
   import VirtualMachine.Types
   import Data.Array.IO
 
-  {-
+  {- |
     Constructs a stack frame from the passed method. Each stack frame keeps track
     of it's local variables, operand stack, and code segment, which is composed
     of the instructions and the current program counter.
@@ -32,39 +32,39 @@ module VirtualMachine.Stack_Frame where
               | n > 0 = (:) <$> newIORef (VReference 0) <*> createLocals (n - 1)
               | otherwise = error $ "Error while attempting to create locals: n=" ++ show n
 
-  {- Obtain the reference to the PC of this stack frame -}
+  {- | Obtain the reference to the PC of this stack frame -}
   getPC :: StackFrame -> IO (IORef Word32)
   getPC frame = program_counter . code_segment <$> readIORef frame
 
-  {- Obtain the PC of this stack frame -}
+  {- | Obtain the PC of this stack frame -}
   getPC' :: Integral a => StackFrame -> IO a
   getPC' frame = getPC frame >>= \f -> fromIntegral <$> readIORef f
 
-  {- Set the PC of this stack frame -}
+  {- | Set the PC of this stack frame -}
   setPC :: Integral a => StackFrame -> a -> IO ()
   setPC frame pc = getPC frame >>= flip writeIORef (fromIntegral pc)
 
-  {- Mutate the PC of this stack frame -}
+  {- | Mutate the PC of this stack frame -}
   modifyPC :: Integral a => StackFrame -> (a -> a) -> IO ()
   modifyPC frame f = (f <$> getPC' frame) >>= setPC frame
 
-  {- Maximum PC for this stack frame (without going out of bounds) -}
+  {- | Maximum PC for this stack frame (without going out of bounds) -}
   maxPC :: Integral a => StackFrame -> IO a
   maxPC frame = fromIntegral . length <$> getInstructions frame
 
   getInstructions :: StackFrame -> IO Instructions
   getInstructions frame = byte_code . code_segment <$> readIORef frame
 
-  {- Pushes a value on the operand stack -}
+  {- | Pushes a value on the operand stack -}
   pushOp :: StackFrame -> Value -> IO ()
   pushOp frame val = (operand_stack <$> readIORef frame) >>= flip modifyIORef (val :)
 
-  {- Pops the operand off of the stack -}
+  {- | Pops the operand off of the stack -}
   popOp :: StackFrame -> IO Value
   popOp frame = readIORef frame >>= \f -> readIORef (operand_stack f)
     >>= \ops -> writeIORef (operand_stack f) (tail ops) >> return (head ops)
 
-  {-
+  {- |
     Pushes a value as a local variable at the given index.
   -}
   putLocal :: (Integral a) => StackFrame -> a -> Value -> IO ()
@@ -73,10 +73,10 @@ module VirtualMachine.Stack_Frame where
   modifyLocal :: (Integral a) => StackFrame -> a -> (Value -> Value) -> IO ()
   modifyLocal frame idx f = getLocal frame idx >>= flip modifyIORef f
 
-  {- Returns the value of the local variable. -}
+  {- | Returns the value of the local variable. -}
   getLocal' :: (Integral a) => StackFrame -> a -> IO Value
   getLocal' frame idx = readIORef frame >>= \f -> readIORef (local_variables f !! fromIntegral idx)
 
-  {- Returns a reference to the local variable -}
+  {- | Returns a reference to the local variable -}
   getLocal :: Integral a => StackFrame -> a -> IO (IORef Value)
   getLocal frame idx = (!! fromIntegral idx) . local_variables <$> readIORef frame

VirtualMachine/Types.hs

@@ -97,33 +97,33 @@ module VirtualMachine.Types where
 
   type Operand = Value
 
-  {- Runtime representation of a method -}
+  {- | Runtime representation of a method -}
   data Method = Method {
     method_code :: Instructions,
     method_locals :: Word16
   }
 
-  {- Runtime representation of a field -}
+  {- | Runtime representation of a field -}
   data Field = Field {
     field_value :: Value
   }
 
-  {- Runtime representation of a Class -}
+  {- | Runtime representation of a Class -}
   data Class = Class {
     constant_pool :: [CP_Info],
     method_map :: IORef (Map String Method),
     field_map :: IORef (Map String Field)
   }
 
-  {- Representation of a runtime environment -}
+  {- | Representation of a runtime environment -}
   data Runtime_Environment = Environment {
     current_class :: IORef Class,
     class_map :: IORef (Map String Class),
     stack :: Stack,
     debug_mode :: Bool
   }
 
-  {- Representation of a stack frame. -}
+  {- | Representation of a stack frame. -}
   data Stack_Frame = Frame {
     local_variables :: [Local_Variable],
     operand_stack :: IORef [Operand],