commented Interpreter class

diff --git a/src/loader/Interpreter.h b/src/loader/Interpreter.h
index 5a8e3ab8aa424ed4db977e0c471c475cea05b8af..1a73d2dce69c54591354a2ae09fdd9234d03df91 100644 (file)
--- a/src/loader/Interpreter.h
+++ b/src/loader/Interpreter.h
@@ -26,23 +26,46 @@ public:
        static const int STRING_ID = 7;
        static const int VECTOR_ID = 8;
 
+       /// Instances of this class are thrown if an
+       /// interpretation error is encounteres such as a
+       /// reference to an undeclared or inlining of an undefined
+       /// object.
        class Error: public std::runtime_error {
        public:
-               Error(const std::string &msg) : std::runtime_error("interpreter error: " + msg) { }
+               Error(const std::string &msg)
+               : std::runtime_error("interpreter error: " + msg) { }
        };
 
 public:
-       explicit Interpreter(const ParsedSource &source) : source(source), alloc(4096) { }
+       /// Create an interpreter that rads from given parsed
+       /// source.
+       /// After creation you should call ReadSource() before
+       /// querying e.g. with GetObject().
+       explicit Interpreter(const ParsedSource &source)
+       : source(source), alloc(4096) { }
        ~Interpreter();
 private:
        Interpreter(const Interpreter &);
        Interpreter &operator =(const Interpreter &);
 
 public:
+       /// Interpret all exported definitions of the underlying
+       /// source file.
        void ReadSource();
+       /// Get an object of given type that is defined by given
+       /// name.
+       /// If the object identified by name is of another type,
+       /// a cast is performed for compatible types.
+       /// Error is thrown if the object is undefined or a cast
+       /// was unsuccessful.
        void *GetObject(int typeId, const std::string &name);
 
+       /// Register the type descriptions of builtin types.
+       /// This should be called before any interpretation (like
+       /// calling ReadSource()) is performed.
        static void CreateTypeDescriptions();
+       /// Represents a parsed definition with resulting type and
+       /// object IDs.
        struct ParsedDefinition {
                ParsedDefinition(const Definition *dfn, int type, int id)
                : dfn(dfn), type(type), id(id) { }
@@ -50,6 +73,11 @@ public:
                int type;
                int id;
        };
+       /// Represents a postponed object where the type and
+       /// target location are already known, but the definition
+       /// was not accessible at interpretation time.
+       /// It could become available later or be dynamically
+       /// linked by its identifier.
        struct PostponedDefinition {
                PostponedDefinition(
                                char *dest,
@@ -69,30 +97,77 @@ public:
                bool aggregate;
        };
 
-       const std::set<std::string> &ExportedIdentifiers() const { return source.Exports(); }
+       /// Get all the identifiers that are marked for export
+       /// by name in the source.
+       const std::set<std::string> &ExportedIdentifiers() const {
+               return source.Exports();
+       }
+       /// Get the object definition for given identifier.
        const ParsedDefinition &GetDefinition(const std::string &identifier);
-       const std::map<std::string, SDL_Surface *> &Images() const { return imageCache; }
-       const std::vector<PostponedDefinition> &PostponedDefinitions() const { return postponedDefinitions; }
-       const std::map<int, std::vector<void *> > &Values() const { return values; }
+       /// Get all images reference by he source.
+       /// The returned map is indexed by filenames relative to
+       /// the source file and contains ready-to-blit surfaces.
+       const std::map<std::string, SDL_Surface *> &Images() const {
+               return imageCache;
+       }
+       /// Get all definitions that were postponed because they
+       /// were not in the parsed source.
+       const std::vector<PostponedDefinition> &PostponedDefinitions() const {
+               return postponedDefinitions;
+       }
+       /// A map of object id to object.
+       const std::map<int, std::vector<void *> > &Values() const {
+               return values;
+       }
 
 private:
+       /// Interpret given definition.
        void ReadDefinition(const Definition &);
+       /// Interpret given definition as a literal.
        void ReadLiteral(const Definition &);
+       /// Interpret given definition as a complex object.
        void ReadObject(const Definition &);
 
+       /// Interpret given literal as an object of given type.
+       /// The resulting object shall be accessible by given ID
+       /// (whiich is already reserved) and be written to given
+       /// destination.
        void ReadLiteral(int typeId, int id, char *dest, const Literal &);
+       /// Get an object of given type from given value.
+       /// The object will be registere as new and be given a
+       /// unique ID.
+       /// Any nested objects will be created likewise.
        void *GetObject(int typeId, const Value &value);
+       /// Read an object of given type and properties into dest.
+       /// The object should alrady have an assigned identifier.
+       /// Pass -1 as ID if the object is anonymous.
+       /// Note that anonymous objects must not contain
+       /// references as they are excluded from linking.
        void ReadObject(int typeId, int id, char *dest, const PropertyList &);
+       /// The function that does the actual compiling when you
+       /// call ReadScript(const vector<ScriptToken *> &).
        void ReadScript(const std::vector<ScriptToken *> &, common::Script *);
+       /// Compile a tokenized script.
+       /// Storage for the script will be allocated as neccessary.
        char *ReadScript(const std::vector<ScriptToken *> &);
+       /// Reinterpret dest as a script code and return a
+       /// reference to that.
        common::Script::Code &CreateScriptCode(common::Script::Command c, char *dest);
+       /// Write address to dest.
        void ReadScriptAddress(const ScriptToken &t, char *dest);
+       /// Write integer to est.
        void ReadScriptInteger(const ScriptToken &t, char *dest);
+       /// Write vector to dest.
        void ReadScriptVector(const ScriptToken &t, char *dest);
 
+       /// Get a surface from given image path.
+       /// Load it if neccessary.
        SDL_Surface *GetImage(const std::string &);
 
+       /// Check if a value can be linked right now or if linkage
+       /// must be deferred (with Postpone()).
        bool CanLink(const Value &) const;
+       /// Defer linking of given object reference.
        void Postpone(
                        char *dest,
                        const std::string &identifier,