Document a lot of classes and functions

[builder.git] / source / target.h

diff --git a/source/target.h b/source/target.h
index 8a394f3717625787dbc1c123b7bd4f61319da8da..f4a4efc9a262ee55cf145f56fe5a4fc1d7602d99 100644 (file)
--- a/source/target.h
+++ b/source/target.h
@@ -63,13 +63,15 @@ public:
        returns 0. */
        virtual Target *get_buildable_target();
 
-       /** If this target is a proxy for another (such as Install), return that
-       target.  Otherwise, return the target itself.
-
-       Implementors should call the function recursively to find the final target. */
+       /** If this target is a proxy for another (such as InstalledFile), return
+       that target.  Otherwise, return the target itself.  Implementors should call
+       the function recursively to find the final target. */
        virtual Target *get_real_target() { return this; }
 
        void set_tool(const Tool &);
+
+       /** Returns the tool used to build the target.  To actually build it, call
+       the build() function. */
        const Tool *get_tool() const { return tool; }
 
        /** Indicates if it's possible to build this target. */
@@ -86,19 +88,29 @@ public:
        /** Forces rebuild of the target. */
        void force_rebuild();
 
+       /** Adds a dependency for the target.  Order is preseved and is important
+       for some target types.  It is an error to create dependency cycles, although
+       this won't be detected until the targets are prepared. */
        void add_depend(Target *);
+
+       /// Returns the dependencies of the target, in the order they were added.
        const Dependencies &get_depends() const { return depends; }
 
-       /** Finds dependencies for the target. */
+       /** Finds dependencies for the target.  Called during preparation.  If the
+       target needs to recursively inspect its dependencies, it should prepare its
+       direct dependencies first. */
        virtual void find_depends() { }
 
        /** Prepares the target by finding dependencies, recursively preparing them
        and then checking whether rebuilding is needed. */
        virtual void prepare();
 
-       /** Starts building the target.  Returns the Action used for building. */
+       /** Invokes the associated Tool to build the target and returns the
+       resulting Task.  The task must be started by the caller. */
        Task *build();
+
 protected:
+       /** Marks the target to be rebuilt and specified a reason for it. */
        void mark_rebuild(const std::string &);
 
        /** Checks if the target needs to be rebuilt and why. */