[cmake-commits] king committed cmSourceFileLocation.h 1.1.2.1 1.1.2.2

[cmake-commits at cmake.org]

Update of /cvsroot/CMake/CMake/Source
In directory public:/mounts/ram/cvs-serv31417

Modified Files:
      Tag: CMake-SourceFile2-b
	cmSourceFileLocation.h 
Log Message:
STYLE: Added interface documentation.


Index: cmSourceFileLocation.h
===================================================================
RCS file: /cvsroot/CMake/CMake/Source/Attic/cmSourceFileLocation.h,v
retrieving revision 1.1.2.1
retrieving revision 1.1.2.2
diff -u -d -r1.1.2.1 -r1.1.2.2
--- cmSourceFileLocation.h	11 Jun 2007 22:23:34 -0000	1.1.2.1
+++ cmSourceFileLocation.h	13 Jun 2007 20:33:22 -0000	1.1.2.2
@@ -22,22 +22,70 @@
 class cmMakefile;
 
 /** \class cmSourceFileLocation
- * \brief
+ * \brief cmSourceFileLocation tracks knowledge about a source file location
  *
- * cmSourceFileLocation
+ * Source files can be referenced by a variety of names.  The
+ * directory and/or extension may be omitted leading to a certain
+ * level of ambiguity about the source file location.  This class is
+ * used by cmSourceFile to keep track of what is known about the
+ * source file location.  Each reference may add some information
+ * about the directory or extension of the file.
  */
 class cmSourceFileLocation
 {
 public:
+  /**
+   * Construct for a source file created in a given cmMakefile
+   * instance with an initial name.
+   */
   cmSourceFileLocation(cmMakefile* mf, const char* name);
+
+  /**
+   * Return whether the givne source file location could refers to the
+   * same source file as this location given the level of ambiguity in
+   * each location.
+   */
   bool Matches(cmSourceFileLocation const& loc);
 
+  /**
+   * Explicity state that the source file is located in the source tree.
+   */
   void DirectoryUseSource();
+
+  /**
+   * Explicity state that the source file is located in the build tree.
+   */
   void DirectoryUseBinary();
+
+  /**
+   * Return whether the directory containing the source is ambiguous.
+   */
   bool DirectoryIsAmbiguous() const { return this->AmbiguousDirectory; }
+
+  /**
+   * Return whether the extension of the source name is ambiguous.
+   */
   bool ExtensionIsAmbiguous() const { return this->AmbiguousExtension; }
+
+  /**
+   * Get the directory containing the file as best is currently known.
+   * If DirectoryIsAmbiguous() returns false this will be a full path.
+   * Otherwise it will be a relative path (possibly empty) that is
+   * either with respect to the source or build tree.
+   */
   const char* GetDirectory() const { return this->Directory.c_str(); }
+
+  /**
+   * Get the file name as best is currently known.  If
+   * ExtensionIsAmbiguous() returns true this name may not be the
+   * final name (but could be).  Otherwise the returned name is the
+   * final name.
+   */
   const char* GetName() const { return this->Name.c_str(); }
+
+  /**
+   * Get the cmMakefile instance for which the source file was created.
+   */
   cmMakefile* GetMakefile() const { return this->Makefile; }
 private:
   cmMakefile* Makefile;
@@ -46,6 +94,7 @@
   std::string Directory;
   std::string Name;
 
+  // Update the location with additional knowledge.
   void Update(cmSourceFileLocation const& loc);
   void Update(const char* name);
   void UpdateExtension(const char* name);