Changeset 12861

Timestamp:

08/05/10 19:16:22 (13 years ago)

Author:

ehuelsmann

Message:

Add documentation and some TODOs.

File:

• branches/generic-class-file/abcl/src/org/armedbear/lisp/jvm-class-file.lisp (modified) (27 diffs)

branches/generic-class-file/abcl/src/org/armedbear/lisp/jvm-class-file.lisp

@@ -280 +280 @@
                            (:include constant
                                      (tag 7)))
+  "Structure holding information on a 'class' type item in the constant pool."
   name-index)
 
@@ -286 +287 @@
                                      (tag index class-index name/type-index))
                                 (:include constant))
+  "Structure holding information on a member reference type item
+(a field, method or interface method reference) in the constant pool."
   class-index
   name/type-index)
@@ -308 +311 @@
                             (:include constant
                                       (tag 8)))
+  "Structure holding information on a 'string' type item in the constant pool."
   value-index)
 
@@ -313 +317 @@
                                 %make-constant-float/int (tag index value))
                                (:include constant))
+  "Structure holding information on a 'float' or 'integer' type item
+in the constant pool."
   value)
 
@@ -327 +333 @@
                                   %make-constant-double/long (tag index value))
                                  (:include constant))
+  "Structure holding information on a 'double' or 'long' type item
+in the constant pool."
   value)
 
@@ -344 +352 @@
                                (:include constant
                                          (tag 12)))
+  "Structure holding information on a 'name-and-type' type item in the
+constant pool; this type of element is used by 'member-ref' type items."
   name-index
   descriptor-index)
@@ -350 +360 @@
                           (:include constant
                                     (tag 1)))
+  "Structure holding information on a 'utf8' type item in the constant pool;
+
+This type of item is used for text representation of identifiers
+and string contents."
   value)
 
@@ -489 +503 @@
 (defstruct (class-file (:constructor
                         !make-class-file (class superclass access-flags)))
+  "Holds the components of a class file."
   (constants (make-pool))
   access-flags
   class
   superclass
+  ;; support for implementing interfaces not yet available
   ;; interfaces
   fields
@@ -690 +706 @@
 
 (defstruct (field (:constructor %make-field))
-  ""
+  "Holds information on the properties of fields in the class(-file)."
   access-flags
   name
@@ -697 +713 @@
 
 (defun !make-field (name type &key (flags '(:public)))
-  
+  "Creates a field for addition to a class file."
   (%make-field :access-flags flags
                :name name
@@ -703 +719 @@
 
 (defun field-add-attribute (field attribute)
+  "Adds an attribute to a field."
   (push attribute (field-attributes field)))
 
 (defun field-attribute (field name)
+  "Retrieves an attribute named `name' of `field'.
+
+Returns NIL if the attribute isn't found."
   (find name (field-attributes field)
         :test #'string= :key #'attribute-name))
 
 (defun finalize-field (field class)
+  "Prepares `field' for serialization."
   (let ((pool (class-file-constants class)))
     (setf (field-access-flags field)
@@ -720 +741 @@
 
 (defun !write-field (field stream)
+  "Writes classfile representation of `field' to `stream'."
   (write-u2 (field-access-flags field) stream)
   (write-u2 (field-name field) stream)
@@ -727 +749 @@
 
 (defstruct (method (:constructor %!make-method))
+  "Holds information on the properties of methods in the class(-file)."
   access-flags
   name
@@ -748 +771 @@
 
 (defun !make-method (name return args &key (flags '(:public)))
+  "Creates a method for addition to a class file."
   (%!make-method :descriptor (cons return args)
                 :access-flags flags
@@ -776 +800 @@
 
 (defun method-attribute (method name)
+  "Returns the first attribute of `method' with `name'."
   (find name (method-attributes method)
         :test #'string= :key #'attribute-name))
@@ -781 +806 @@
 
 (defun finalize-method (method class)
+  "Prepares `method' for serialization."
   (let ((pool (class-file-constants class)))
     (setf (method-access-flags method)
@@ -792 +818 @@
 
 (defun !write-method (method stream)
+  "Write class file representation of `method' to `stream'."
   (write-u2 (method-access-flags method) stream)
   (write-u2 (method-name method) stream)
@@ -799 +826 @@
 
 (defstruct attribute
+  "Parent attribute structure to be included into other attributes, mainly
+to define common fields.
+
+Having common fields allows common driver code for
+finalizing and serializing attributes."
   name
 
@@ -807 +839 @@
 
 (defun finalize-attributes (attributes att class)
+  "Prepare `attributes' (a list) of attribute `att' list for serialization."
   (dolist (attribute attributes)
     ;; assure header: make sure 'name' is in the pool
@@ -816 +849 @@
 
 (defun write-attributes (attributes stream)
+  "Writes the `attributes' to `stream'."
   (write-u2 (length attributes) stream)
   (dolist (attribute attributes)
@@ -835 +869 @@
                                      (writer #'!write-code))
                            (:constructor %make-code-attribute))
+  "The attribute containing the actual JVM byte code;
+an attribute of a method."
   max-stack
   max-locals
@@ -851 +887 @@
 
 (defun code-label-offset (code label)
+  "Retrieves the `label' offset within a `code' attribute after the
+attribute has been finalized."
   (cdr (assoc label (code-labels code))))
 
 (defun (setf code-label-offset) (offset code label)
+  "Sets the `label' offset within a `code' attribute after the attribute
+has been finalized."
   (setf (code-labels code)
         (acons label offset (code-labels code))))
 
-
-
 (defun !finalize-code (code parent class)
+  "Prepares the `code' attribute for serialization, within method `parent'."
   (declare (ignore parent))
   (let ((c (resolve-instructions (coerce (reverse (code-code code)) 'vector))))
@@ -885 +924 @@
 
 (defun !write-code (code stream)
+  "Writes the attribute `code' to `stream'."
   (sys::%format t "max-stack: ~a~%" (code-max-stack code))
   (write-u2 (code-max-stack code) stream)
@@ -918 +958 @@
 
 (defun code-attribute (code name)
+  "Returns an attribute of `code' identified by `name'."
   (find name (code-attributes code)
         :test #'string= :key #'attribute-name))
@@ -923 +964 @@
 
 (defun code-add-exception-handler (code start end handler type)
+  "Adds an exception handler to `code' protecting the region from
+labels `start' to `end' (inclusive) from exception `type' - where
+a value of NIL indicates all types. Upon an exception of the given
+type, control is transferred to label `handler'."
   (push (make-exception :start-pc start
                         :end-pc end
@@ -930 +975 @@
 
 (defstruct exception
+  "Exception handler information.
+
+After finalization, the fields contain offsets instead of labels."
   start-pc    ;; label target
   end-pc      ;; label target
@@ -974 +1022 @@
 
 
+;; ### Can't be used yet: no serialization
 (defstruct (source-file-attribute (:conc-name source-)
                                   (:include attribute
                                             (name "SourceFile")))
+  "An attribute of the class file indicating which source file
+it was compiled from."
   filename)
 
+;; ### Can't be used yet: no serialization
 (defstruct (line-numbers-attribute (:include attribute
                                              (name "LineNumberTable")))
-  line-numbers)
+  "An attribute of `code-attribute', containing a mapping of offsets
+within the code section to the line numbers in the source file."
+  line-numbers ;; a list of line-number structures, in reverse order
+  )
 
 (defstruct line-number
-  start-pc
+  start-pc  ;; a label, before finalization
   line)
 
+;; ### Can't be used yet: no serialization
 (defstruct (local-variables-attribute (:conc-name local-var-)
                                       (:include attribute
                                                 (name "LocalVariableTable")))
-  locals)
+  "An attribute of the `code-attribute', containing a table of local variable
+names, their type and their scope of validity."
+  locals ;; a list of local-variable structures, in reverse order
+  )
 
 (defstruct (local-variable (:conc-name local-))
-  start-pc
+  start-pc  ;; a label, before finalization
   length
   name
   descriptor
-  index)
+  index ;; The index of the variable inside the block of locals
+  )
 
 #|