A bit of documentation and explenations for backbone

diff --git a/trunk/src/base/backbone/backbone.cpp b/trunk/src/base/backbone/backbone.cpp
index e65582f..713f504 100644 (file)
--- a/trunk/src/base/backbone/backbone.cpp
+++ b/trunk/src/base/backbone/backbone.cpp
@@ -31,7 +31,8 @@
 int Backbone::_searchLimit;
 
 // Sadly QtConcurent::mapped dosent let me use something like calling method of
-// some class with supplied argument
+// some class with supplied argument; so i have to sin against art and put
+// global function and variable so i could supply function with some parametr
 QString mappedSearch;
 QList<Translation*> mapSearch(CommonDictInterface *dict) {
     if(dict)
@@ -39,10 +40,25 @@ QList<Translation*> mapSearch(CommonDictInterface *dict) {
     return QList<Translation*>();
 }
 
+
+
+/*! Smart pointer (kind of) for translation object
+
+    QtConcurent::mapped  use collection of data and one function, what i need is
+    to map signle data object to method calls for multiple objects. TranslationPtr
+    is try to store method call as a data -> moreover QtConcurent allow only for
+    methods without any parameters so TranslationPtr is created with Translation
+    object -> ready to call toHtml() for supplied Translation.
+
+    Another thing is that QtConcurent dont like pointers in data collection
+    so TranslationPtr is way to hide real translation object (pointer for object)
+    */
 class TranslationPtr {
     Translation* _tr;
 public:
     TranslationPtr(Translation* tr) :_tr(tr) {}
+
+    /*! \return translation text for corresponding Translation object */
     QString toHtml() const {
         QString trans;
         trans = _tr->toHtml();
@@ -63,6 +79,9 @@ void Backbone::init() {
    _searchLimit = 15;
 
    loadPrefs(_defaultConfigPath);
+
+   // Default configuration are stored in separate config file and we dont want
+   // to update it
    _defaultPluginPath = _pluginPath;
    _defaultHistoryLen = _historyLen;
    _defaultSearchLimit = _searchLimit;
@@ -81,6 +100,8 @@ void Backbone::init() {
    connect(&_bookmarkSearchWatcher, SIGNAL(finished()), this,
            SLOT(translationReady()));
 
+   // In common opinion perfect thread count is cores_number+1 (in qt perfect
+   // thread count is set to cores number
    QThreadPool::globalInstance()->setMaxThreadCount(
            QThreadPool::globalInstance()->maxThreadCount()+1);
 
@@ -96,6 +117,7 @@ Backbone::Backbone(QString pluginPath, QString configPath, bool dry,
 {
     _pluginPath = pluginPath;
     _configPath = configPath;
+
     _defaultConfigPath = configPath;
     dryRun = false;
     if(dry)
@@ -184,6 +206,11 @@ void Backbone::search(QString word){
     mappedSearch = word.toLower();
 
     stopped = false;
+
+    // When dictFin and bookmarkFin is set to true then translationReady()
+    // signal is emited see translationReady(),
+    // so when searching only in one of them, coresponding *Fin is set to false
+    // and other to true so program is waiting only for one translation
     dictFin = !_searchDicts;
     bookmarkFin = !_searchBookmarks;
 
@@ -220,8 +247,9 @@ void Backbone::addDictionary(CommonDictInterface *dict, bool active) {
 
 
  void Backbone::addInternalDictionary(CommonDictInterface* dict, bool active) {
-     dict->setHash(++_dictNum);
+     dict->setHash(++_dictNum); // Hash must be uniqe in every session but not between
      _dicts[dict] = active;
+
      connect(dict, SIGNAL(settingsChanged()), this, SLOT(dictUpdated()));
      connect(dict, SIGNAL(notify(Notify::NotifyType,QString)), this,
              SIGNAL(notify(Notify::NotifyType,QString)));
@@ -244,9 +272,10 @@ void Backbone::addDictionary(CommonDictInterface *dict, bool active) {
 
 
 void Backbone::translationReady() {
-    bool changed = 0; // prevents doubling ready() signal, when both if are
+    bool changed = 0; // prevents doubling ready() signal, when both if's are
                       //  executed in one translationReady() call then second
-                      // call doubles ready*() emit without any new data
+                      // translationReady() call doubles ready*() emit
+
     if(!dictFin && _innerResult.isFinished()) {
         changed = 1;
         dictFin = 1;
@@ -270,7 +299,7 @@ void Backbone::translationReady() {
 
     if(!stopped && bookmarkFin && dictFin && changed) {
         Q_EMIT ready();
-        }
+    }
 }
 
 QStringList Backbone::getFilesFromDir(QString dir, QStringList nameFilter) {
@@ -372,6 +401,7 @@ void Backbone::saveDefaultPrefs(QSettings *set) {
 void Backbone::loadDicts(QString fileName, bool _default) {
     if(dryRun)
         return;
+
     QFileInfo file(QDir::toNativeSeparators(fileName));
     QDir confDir(file.dir());
     if(!confDir.exists()){
@@ -420,6 +450,12 @@ void Backbone::loadDicts(QString fileName, bool _default) {
 void Backbone::dictUpdated() {
     if(dryRun)
         return;
+
+    // For convienence this function is called for each change in dictionaries
+    // and each call dumps configuration for all dictionaries into file.
+    // Maybe better way would be to store new/changed configuration but
+    // parsing settings file and figuring out what was changed, in my opinion,
+    // would take more time
     _history->setMaxSize(_historyLen);
     QFileInfo file(QDir::toNativeSeparators(_configPath));
     QDir confDir(file.dir());
@@ -455,6 +491,7 @@ void Backbone::saveState(QSettings* set, Settings* plugSet, bool active
         return;
     if(!set || !plugSet)
         return;
+
     QString section;
     section.append(QString("dictionary_%1").arg(hash));
     QList<QString> keys = plugSet->keys();