From: Mikko Rasa Date: Fri, 8 Jun 2012 22:57:28 +0000 (+0300) Subject: Comment updates X-Git-Url: http://git.tdb.fi/?a=commitdiff_plain;h=243d7c7355c1c5d9a0134440f340936325caaf88;p=builder.git Comment updates --- diff --git a/source/buildinfo.h b/source/buildinfo.h index f10e21e..18f33a0 100644 --- a/source/buildinfo.h +++ b/source/buildinfo.h @@ -27,9 +27,9 @@ public: enum UpdateLevel { - LOCAL, - DEPENDENCY, - CHAINED + LOCAL, //< Include all information + DEPENDENCY, //< Include all but code generation options + CHAINED //< Include only compilation options }; typedef std::map DefineMap; @@ -46,7 +46,10 @@ public: BuildInfo(); - /** Adds another BuildInfo to the end of this one. */ + /** Updates the BuildInfo from another one. Lists are concatenated, with + the first occurrence of each item preserved. Scalars are overwritten. + + The update level determines what information is updated. */ void update_from(const BuildInfo &, UpdateLevel = LOCAL); /** Makes sure there are no duplicate entries in the lists. For warnings, diff --git a/source/dependencycache.h b/source/dependencycache.h index a4727aa..4160cec 100644 --- a/source/dependencycache.h +++ b/source/dependencycache.h @@ -7,9 +7,10 @@ class Package; /** -Stores dependencies to avoid expensive operations during DAG building phase. -The dependencies are stored in a map with target name as key and a list of -strings as value. The targets are free to store whatever they want here. +Stores dependencies to avoid expensive filesystem operations during DAG +building phase. The dependencies are stored in a map with target name as key +and a list of strings as value. The targets are free to store whatever they +want here. */ class DependencyCache { @@ -30,9 +31,8 @@ public: const Msp::Time::TimeStamp &get_mtime() const { return mtime; } void load(); - /** - Saves the depencency cache. Does nothing if the cache is empty or nothing - has changed. */ + /** Saves the depencency cache. Does nothing if the cache is empty or + nothing has changed. */ void save() const; }; diff --git a/source/target.h b/source/target.h index d6ed438..03b8755 100644 --- a/source/target.h +++ b/source/target.h @@ -55,19 +55,16 @@ public: const Package *get_package() const { return package; } const Component *get_component() const { return component; } - /** - Tries to locate a target that will help getting this target built. If all - dependencies are up-to-date, returns this target. If there are no targets - ready to be built (maybe because they are being built right now), returns 0. - */ + /** Tries to locate a target that will help getting this target built. If + all dependencies are up-to-date, returns this target. If there are no + targets ready to be built (maybe because they are being built right now), + returns 0. */ virtual Target *get_buildable_target(); - /** - If this target is a proxy for another (such as Install or Symlink), return - that target. Otherwise, return the target itself. + /** 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. - */ + Implementors should call the function recursively to find the final target. */ virtual Target *get_real_target() { return this; } void set_tool(const Tool &); @@ -84,28 +81,19 @@ public: /** Finds dependencies for the target. */ virtual void find_depends() { } - /** - Prepares the target by recursively preparing dependencies, then checking - whether rebuilding is needed. A flag is used to prevent unnecessary - executions. - */ + /** 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. - */ + /** Starts building the target. Returns the Action used for building. */ Task *build(); protected: void mark_rebuild(const std::string &); - /** - Checks if the target needs to be rebuilt and why. - */ + /** Checks if the target needs to be rebuilt and why. */ virtual void check_rebuild() = 0; - /** - Handler for the build_finished signal of Task. - */ + /** Handler for Task::signal_finished. */ virtual void build_finished(bool); }; diff --git a/source/tool.h b/source/tool.h index c302f3c..d1d7103 100644 --- a/source/tool.h +++ b/source/tool.h @@ -10,6 +10,10 @@ class Component; class Target; class Task; +/** +Base class for tools. Tools are used to turn targets into other targets. +Examples include compilers and linkers. +*/ class Tool { public: diff --git a/source/virtualfilesystem.h b/source/virtualfilesystem.h index 7246585..b19d10e 100644 --- a/source/virtualfilesystem.h +++ b/source/virtualfilesystem.h @@ -9,6 +9,11 @@ class Builder; class FileTarget; class Pattern; +/** +Provides access to the filesystem in a way that takes known targets into +account. Thus, targets may be returned for files that do not exist yet if it's +possible to build them. +*/ class VirtualFileSystem { public: @@ -27,31 +32,23 @@ public: FileTarget *get_target(const Msp::FS::Path &) const; + /** Registers a target with the VFS. A target may be registered at multiple + paths if building it results in multiple files. */ void register_path(const Msp::FS::Path &, FileTarget *); - /** Tries to locate a header based on location of including file and include - path. Considers known targets as well as existing files. If a matching - target is not found but a file exists, a new SystemHeader target will be - created and returned. */ + /** Locates a source file. If a file is found but no target is associated + with it, a new package-less target is created with the appropriate tool. */ FileTarget *find_header(const std::string &, const SearchPath &); - /** Tries to locate a library in a library path. The library name should be - the same as would be given to the linker with -l, i.e. without the "lib" - prefix or extension. Considers known targets as well as existing files. If - a matching target is not found but a file exists, a new SystemLibrary target - will be created and returned. */ + /** Locates a library. The library name should be the same as what would be + used in linking with the library. If a file is found but no target is + associated with it, a new package-less target of appropriate type is + created. */ FileTarget *find_library(const std::string &, const SearchPath &, LibMode); private: - /** - Check if a header exists, either as a target or a file. Returns an existing - target of one was found, or a new SystemHeader target if there was no known - target but the file exists. - */ FileTarget *get_header(const Msp::FS::Path &, const Tool &); - FileTarget *get_library(const std::string &, const Msp::FS::Path &, LibMode); - Msp::FS::Path try_patterns(const Msp::FS::Path &, const std::list &, const std::string &); };