ENH: add help for cache entries

Source/MFCDialog/CMakeSetupDialog.cpp

@@ -388,25 +388,33 @@ void CMakeSetupDialog::FillCacheGUIFromCacheManager()
           {
           m_CacheEntriesList.AddProperty(key,
                                          "ON",
+                                         value.m_HelpString.c_str(),
                                          CPropertyList::CHECKBOX,"");
           }
         else
           {
           m_CacheEntriesList.AddProperty(key,
                                          "OFF",
+                                         value.m_HelpString.c_str(),
                                          CPropertyList::CHECKBOX,"");
           }
         break;
       case cmCacheManager::PATH:
-        m_CacheEntriesList.AddProperty(key, value.m_Value.c_str(),
+        m_CacheEntriesList.AddProperty(key, 
+                                       value.m_Value.c_str(),
+                                       value.m_HelpString.c_str(),
                                        CPropertyList::PATH,"");
         break;
       case cmCacheManager::FILEPATH:
-        m_CacheEntriesList.AddProperty(key, value.m_Value.c_str(),
+        m_CacheEntriesList.AddProperty(key, 
+                                       value.m_Value.c_str(),
+                                       value.m_HelpString.c_str(),
                                        CPropertyList::FILE,"");
         break;
       case cmCacheManager::STRING:
-        m_CacheEntriesList.AddProperty(key, value.m_Value.c_str(),
+        m_CacheEntriesList.AddProperty(key,
+                                       value.m_Value.c_str(),
+                                       value.m_HelpString.c_str(),
                                        CPropertyList::EDIT,"");
         break;
       case cmCacheManager::INTERNAL:

Source/MFCDialog/PropertyList.cpp

@@ -44,6 +44,7 @@ BEGIN_MESSAGE_MAP(CPropertyList, CListBox)
   ON_BN_CLICKED(IDC_PROPBTNCTRL, OnButton)
   ON_BN_CLICKED(IDC_PROPCHECKBOXCTRL, OnCheckBox)
   ON_COMMAND(42, OnDelete)
+  ON_COMMAND(43, OnHelp)
 END_MESSAGE_MAP()
 
 /////////////////////////////////////////////////////////////////////////////
@@ -123,6 +124,7 @@ int CPropertyList::AddPropItem(CPropertyItem* pItem)
 
 int CPropertyList::AddProperty(const char* name,
                                const char* value,
+                               const char* helpString,
                                int type,
                                const char* comboItems)
 { 
@@ -136,6 +138,7 @@ int CPropertyList::AddProperty(const char* name,
       if(pItem->m_curValue != value)
         {
         pItem->m_curValue = value;
+        pItem->m_HelpString = helpString;
         m_Dirty = true;
         Invalidate();
         }
@@ -154,13 +157,14 @@ int CPropertyList::AddProperty(const char* name,
       pItem = *p;
       pItem->m_Removed = false;
       pItem->m_curValue = value; 
+      pItem->m_HelpString = helpString;
       Invalidate();
       }
     }
   // if it is not found, then create a new one
   if(!pItem)
     {
-    pItem = new CPropertyItem(name, value, type, comboItems);
+    pItem = new CPropertyItem(name, value, helpString, type, comboItems);
     }
   
   return this->AddPropItem(pItem);
@@ -615,6 +619,7 @@ void CPropertyList::OnRButtonUp( UINT nFlags, CPoint point )
   m_curSel = ItemFromPoint(point,loc);
   menu.CreatePopupMenu();
   menu.AppendMenu(MF_STRING | MF_ENABLED, 42, "Delete Cache Entry");
+  menu.AppendMenu(MF_STRING | MF_ENABLED, 43, "Help For Cache Entry");
   menu.TrackPopupMenu(TPM_LEFTALIGN | TPM_RIGHTBUTTON, 
                       rect.TopLeft().x + point.x,
                       rect.TopLeft().y + point.y, this, NULL);
@@ -629,6 +634,12 @@ void CPropertyList::OnDelete()
   Invalidate();
 }
 
+void CPropertyList::OnHelp()
+{ 
+  CPropertyItem* pItem = (CPropertyItem*) GetItemDataPtr(m_curSel);
+  MessageBox(pItem->m_HelpString);
+}
+
 void CPropertyList::RemoveAll()
 {
   int c = this->GetCount();

Source/MFCDialog/PropertyList.h

@@ -11,6 +11,7 @@ class CPropertyItem
 {
 // Attributes
 public:
+  CString m_HelpString;
   CString m_propName;
   CString m_curValue;
   int m_nItemType;
@@ -18,8 +19,10 @@ public:
   bool m_Removed;
 public:
   CPropertyItem(CString propName, CString curValue,
+                CString helpString,
                 int nItemType, CString cmbItems)
     {
+      m_HelpString = helpString;
       m_Removed = false;
       m_propName = propName;
       m_curValue = curValue;
@@ -55,6 +58,7 @@ public:
   int AddItem(CString txt);
   int AddProperty(const char* name,
                   const char* value,
+                  const char* helpString,
                   int type,
                   const char* comboItems);
   std::set<CPropertyItem*> GetItems() 
@@ -95,6 +99,7 @@ protected:
   afx_msg void OnChangeEditBox();
   afx_msg void OnButton();
   afx_msg void OnDelete();
+  afx_msg void OnHelp();
   afx_msg void OnCheckBox();
 
   DECLARE_MESSAGE_MAP()

Source/cmAddLibraryCommand.cxx

@@ -34,7 +34,7 @@ bool cmAddLibraryCommand::Invoke(std::vector<std::string>& args)
   cmCacheManager::GetInstance()->
     AddCacheEntry(args[0].c_str(),
                   m_Makefile->GetCurrentOutputDirectory(),
-                  cmCacheManager::INTERNAL);
+                  "Path to a library", cmCacheManager::INTERNAL);
   return true;
 }
 

Source/cmBuildSharedLibrariesCommand.cxx

@@ -24,7 +24,11 @@ bool cmBuildSharedLibrariesCommand::Invoke(std::vector<std::string>& args)
     = cmCacheManager::GetInstance()->GetCacheValue("BUILD_SHARED_LIBS");
   if(!cacheValue)
     {
-    cmCacheManager::GetInstance()->AddCacheEntry("BUILD_SHARED_LIBS",false);
+    cmCacheManager::GetInstance()->
+      AddCacheEntry("BUILD_SHARED_LIBS",
+                    false,
+                    "If ON, the resulting project or makefiles will "
+                    "produce shared libraries.");
     m_Makefile->AddDefinition("BUILD_SHARED_LIBS", false);
     }
   else

Source/cmCacheManager.cxx

@@ -88,6 +88,15 @@ bool cmCacheManager::LoadCache(const char* path)
       {
       continue;
       }
+    while(buffer[0] == '/')
+      {
+      e.m_HelpString += &buffer[2];
+      fin.getline(buffer, bsize);
+      if(!fin)
+        {
+        continue;
+        }
+      }
     if(reg.find(buffer))
       {
       e.m_Type = cmCacheManager::StringToType(reg.match(2).c_str());
@@ -135,11 +144,13 @@ bool cmCacheManager::SaveCache(const char* path) const
   for( std::map<std::string, CacheEntry>::const_iterator i = m_Cache.begin();
        i != m_Cache.end(); ++i)
     {
-    CacheEntryType t = (*i).second.m_Type;
+    const CacheEntry& ce = (*i).second;
+    CacheEntryType t = ce.m_Type;
     // Format is key:type=value
+    cmCacheManager::OutputHelpString(fout, ce.m_HelpString);
     fout << (*i).first.c_str() << ":"
          << cmCacheManagerTypes[t] << "="
-         << (*i).second.m_Value << "\n";
+         << ce.m_Value << "\n";
     }
   fout << "\n";
   fout.close();
@@ -149,21 +160,46 @@ bool cmCacheManager::SaveCache(const char* path) const
   return true;
 }
 
-void cmCacheManager::RemoveCacheEntry(const char* key)
+void cmCacheManager::OutputHelpString(std::ofstream& fout, 
+                                      const std::string& helpString)
 {
-  m_Cache.erase(key);
+  std::string::size_type end = helpString.size();
+  if(end == 0)
+    {
+    return;
+    }
+  std::string oneLine;
+  std::string::size_type pos = 0;
+  std::string::size_type nextBreak = 60;
+  bool done = false;
+
+  while(!done)
+    {
+    if(nextBreak >= end)
+      {
+      nextBreak = end;
+      done = true;
+      }
+    else
+      {
+      while(nextBreak < end && helpString[nextBreak] != ' ')
+        {
+        nextBreak++;
+        }
+      }
+    oneLine = helpString.substr(pos, nextBreak - pos);
+    fout << "//" << oneLine.c_str() << "\n";
+    pos = nextBreak;
+    nextBreak += 60;
+    }
 }
 
-void cmCacheManager::AddCacheEntry(const char* key, 
-				   const char* value, 
-				   CacheEntryType type)
+void cmCacheManager::RemoveCacheEntry(const char* key)
 {
-  CacheEntry e;
-  e.m_Value = value;
-  e.m_Type = type;
-  m_Cache[key] = e;
+  m_Cache.erase(key);
 }
 
+
 cmCacheManager::CacheEntry *cmCacheManager::GetCacheEntry(const char* key)
 {
   if(m_Cache.count(key))
@@ -210,15 +246,28 @@ void cmCacheManager::PrintCache(std::ostream& out) const
 }
 
 
-void cmCacheManager::AddCacheEntry(const char* key, bool v)
+void cmCacheManager::AddCacheEntry(const char* key, 
+                                   const char* value, 
+                                   const char* helpString,
+				   CacheEntryType type)
+{
+  CacheEntry e;
+  e.m_Value = value;
+  e.m_Type = type;
+  e.m_HelpString = helpString;
+  m_Cache[key] = e;
+}
+
+void cmCacheManager::AddCacheEntry(const char* key, bool v, 
+                                   const char* helpString)
 {
   if(v)
     {
-    this->AddCacheEntry(key, "ON", cmCacheManager::BOOL);
+    this->AddCacheEntry(key, "ON", helpString, cmCacheManager::BOOL);
     }
   else
     {
-    this->AddCacheEntry(key, "OFF", cmCacheManager::BOOL);
+    this->AddCacheEntry(key, "OFF", helpString, cmCacheManager::BOOL);
     }
 }
 

Source/cmCacheManager.h

@@ -29,10 +29,10 @@ class cmCacheManager
 {
 public:
   enum CacheEntryType{ BOOL=0, PATH, FILEPATH, STRING, INTERNAL  };
-  class CacheEntry
+  struct CacheEntry
   {
-  public:
     std::string m_Value;
+    std::string m_HelpString;
     CacheEntryType m_Type;
   };
 public:
@@ -60,10 +60,11 @@ public:
   bool SaveCache(const char* path) const;
   
   //! Add an entry into the cache
-  void AddCacheEntry(const char* key, const char* value, CacheEntryType type);
+  void AddCacheEntry(const char* key, const char* value, 
+                     const char* helpString, CacheEntryType type);
 
   //! Add a BOOL entry into the cache
-  void AddCacheEntry(const char* key, bool);
+  void AddCacheEntry(const char* key, bool, const char* helpString);
   
   //! Remove an entry from the cache
   void RemoveCacheEntry(const char* key);
@@ -85,6 +86,8 @@ public:
   const CacheEntryMap &GetCacheMap() const { return m_Cache; }
   
 private:
+  static void OutputHelpString(std::ofstream& fout, 
+                               const std::string& helpString);
   static cmCacheManager* s_Instance;
   CacheEntryMap m_Cache;
 };

Source/cmFindFileCommand.cxx

@@ -68,6 +68,7 @@ bool cmFindFileCommand::Invoke(std::vector<std::string>& args)
       // Save the value in the cache
       cmCacheManager::GetInstance()->AddCacheEntry(define,
                                                    tryPath.c_str(),
+                                                   "Path to a file.",
                                                    cmCacheManager::FILEPATH);
       m_Makefile->AddDefinition(define, tryPath.c_str());
       return true;

Source/cmFindIncludeCommand.cxx

@@ -69,19 +69,23 @@ bool cmFindIncludeCommand::Invoke(std::vector<std::string>& args)
       m_Makefile->AddDefinition(args[0].c_str(), path[k].c_str());
       cmCacheManager::GetInstance()->AddCacheEntry(args[0].c_str(),
                                                    path[k].c_str(),
+                                                   "Find an include path.",
                                                    cmCacheManager::PATH);
       m_Makefile->AddDefinition(args[1].c_str(), args[2].c_str());
       cmCacheManager::GetInstance()->AddCacheEntry(args[1].c_str(),
                                                    args[2].c_str(),
+                                                   "Find an include path.",
                                                    cmCacheManager::PATH);
       return true;
       }
     }
   cmCacheManager::GetInstance()->AddCacheEntry(args[0].c_str(),
                                                "NOTFOUND",
+                                               "Find an include path.",
                                                cmCacheManager::PATH);
   cmCacheManager::GetInstance()->AddCacheEntry(args[1].c_str(),
                                                "NOTFOUND",
+                                               "Find an include path.",
                                                cmCacheManager::PATH);
   std::string message = "Include not found: ";
   message += args[1];

Source/cmFindLibraryCommand.cxx

@@ -61,6 +61,7 @@ bool cmFindLibraryCommand::Invoke(std::vector<std::string>& args)
       m_Makefile->AddDefinition(args[0].c_str(), path[k].c_str());  
       cmCacheManager::GetInstance()->AddCacheEntry(args[0].c_str(),
                                                    path[k].c_str(),
+                                                   "Path to a library",
                                                    cmCacheManager::PATH);
       return true;
       }
@@ -70,6 +71,7 @@ bool cmFindLibraryCommand::Invoke(std::vector<std::string>& args)
       m_Makefile->AddDefinition(args[0].c_str(), path[k].c_str());  
       cmCacheManager::GetInstance()->AddCacheEntry(args[0].c_str(),
                                                    path[k].c_str(),
+                                                   "Path to a library",
                                                    cmCacheManager::PATH);
       return true;
       }
@@ -79,6 +81,7 @@ bool cmFindLibraryCommand::Invoke(std::vector<std::string>& args)
       m_Makefile->AddDefinition(args[0].c_str(), path[k].c_str());  
       cmCacheManager::GetInstance()->AddCacheEntry(args[0].c_str(),
                                                    path[k].c_str(),
+                                                   "Path to a library",
                                                    cmCacheManager::PATH);
       return true;
       }
@@ -86,14 +89,17 @@ bool cmFindLibraryCommand::Invoke(std::vector<std::string>& args)
     if(cmSystemTools::FileExists(testF.c_str()))
       {
       m_Makefile->AddDefinition(args[0].c_str(), path[k].c_str());  
-      cmCacheManager::GetInstance()->AddCacheEntry(args[0].c_str(),
-                                                   path[k].c_str(),
-                                                   cmCacheManager::PATH);
+      cmCacheManager::GetInstance()->
+        AddCacheEntry(args[0].c_str(),
+                      path[k].c_str(),
+                      "Path to a library.",
+                      cmCacheManager::PATH);
       return true;
       }
     }
   cmCacheManager::GetInstance()->AddCacheEntry(args[0].c_str(),
                                                "NOTFOUND",
+                                               "Path to a library",
                                                cmCacheManager::PATH);
   std::string message = "Library not found: ";
   message += args[1];

Source/cmFindPathCommand.cxx

@@ -61,6 +61,7 @@ bool cmFindPathCommand::Invoke(std::vector<std::string>& args)
       m_Makefile->AddDefinition(args[0].c_str(), path[k].c_str());  
       cmCacheManager::GetInstance()->AddCacheEntry(args[0].c_str(),
                                                    path[k].c_str(),
+                                                   "Find a path.",
                                                    cmCacheManager::PATH);
       return true;
       }
@@ -68,6 +69,7 @@ bool cmFindPathCommand::Invoke(std::vector<std::string>& args)
   
   cmCacheManager::GetInstance()->AddCacheEntry(args[0].c_str(),
                                                "NOTFOUND",
+                                               "Find a path.",
                                                cmCacheManager::PATH);
   return true;
 }

Source/cmFindProgramCommand.cxx

@@ -66,6 +66,7 @@ bool cmFindProgramCommand::Invoke(std::vector<std::string>& args)
       // Save the value in the cache
       cmCacheManager::GetInstance()->AddCacheEntry(define,
                                                    tryPath.c_str(),
+                                                   "Path to a program.",
                                                    cmCacheManager::FILEPATH);
       m_Makefile->AddDefinition(define, tryPath.c_str());
       return true;

Source/cmOptionCommand.cxx

@@ -30,7 +30,9 @@ bool cmOptionCommand::Invoke(std::vector<std::string>& args)
     = cmCacheManager::GetInstance()->GetCacheValue(args[0].c_str());
   if(!cacheValue)
     {
-    cmCacheManager::GetInstance()->AddCacheEntry(args[0].c_str(),false);
+    cmCacheManager::GetInstance()->AddCacheEntry(args[0].c_str(),
+                                                 false,
+                                                 "Option command");
     m_Makefile->AddDefinition(args[0].c_str(), "0");
     }
   else

Source/cmUtilitySourceCommand.cxx

@@ -76,6 +76,7 @@ bool cmUtilitySourceCommand::Invoke(std::vector<std::string>& args)
   // Enter the value into the cache.
   cmCacheManager::GetInstance()->AddCacheEntry(cacheEntry.c_str(),
                                                utilityExecutable.c_str(),
+                                               "Path to an internal program.",
                                                cmCacheManager::FILEPATH);
   
   // Set the definition in the makefile.