ENH: add some more comments

Source/cmLocalKdevelopGenerator.cxx

@@ -74,6 +74,8 @@ void cmLocalKdevelopGenerator::Generate(bool fromTheTop)
     }
 }
 
+/* create the project file, if it already exists, merge it with the existing one,
+otherwise create a new one */
 void cmLocalKdevelopGenerator::CreateProjectFile(const std::string& outputDir,
                                                  const std::string& projectDir,
                                                  const std::string& projectname, 
@@ -107,6 +109,9 @@ void cmLocalKdevelopGenerator::MergeProjectFiles(const std::string& outputDir,
     return;
     }
 
+   /* Read the existing project file (line by line), copy all lines into the
+    new project file, except the ones which can be reliably set from contents
+    of the CMakeLists.txt */    
   std::string tmp;
   std::vector<std::string> lines;
   while (cmSystemTools::GetLineFromStream(oldProjectFile, tmp))
@@ -365,6 +370,7 @@ bool cmLocalKdevelopGenerator::CreateFilelistFile(const std::string& outputDir,
     oldFilelist.close();
     }
 
+  //now write the new filename
   cmGeneratedFileStream tempFile(filename.c_str());
   tempFile.SetAlwaysCopy(true);
   std::ostream&  fout = tempFile.GetStream();

Source/cmLocalKdevelopGenerator.h

@@ -26,10 +26,15 @@ class cmTarget;
 class cmSourceFile;
 
 /** \class cmLocalKdevelopGenerator
- * \brief Write a LocalUnix makefiles.
+ * \brief Write Unix Makefiles accompanied by KDevelop3 project files.
  *
- * cmLocalKdevelopGenerator produces a LocalUnix makefile from its
- * member m_Makefile.
+ * cmLocalKdevelopGenerator produces a project file for KDevelop 3 (KDevelop > 3.1.1). 
+ * The project is based on the "Custom Makefile based C/C++" project of KDevelop.
+ * Such a project consists of Unix Makefiles in the build directory together
+ * with a <your_project>.kdevelop project file, which contains the project settings
+ * and a <your_project>.kdevelop.filelist file, which lists the source files relative
+ * to the kdevelop project directory. The kdevelop project directory is the base 
+ * source directory. 
  */
 class cmLocalKdevelopGenerator : public cmLocalUnixMakefileGenerator
 {
@@ -51,11 +56,16 @@ protected:
   /**
     Create the foo.kdevelop file. This one calls MergeProjectFiles() 
     if it already exists, otherwise createNewProjectFile()
+    The project files will be created in \a outputDir (in the build tree), the kdevelop project 
+    dir will  be set to \a projectDir (in the source tree). \a cmakeFilePattern consists of a lists
+    of all cmake listfiles used by this CMakeLists.txt
   */
   void CreateProjectFile(const std::string& outputDir, const std::string& projectDir,
                          const std::string& projectname, const std::string& executable, 
                          const std::string& cmakeFilePattern);
-  ///! Create the foo.kdevelop.filelist file, return false if it doesn't succeed
+  /** Create the foo.kdevelop.filelist file, return false if it doesn't succeed.
+  If the file already exists the contents will be merged.
+  */
   bool CreateFilelistFile(const std::string& outputDir, const std::string& projectDir, 
                           const std::string& projectname, std::string& cmakeFilePattern);
   ///! Reads the old foo.kdevelop line by line and only replaces the "important" lines