Added decomentation and some explenation to dict download mechanism
authorBartosz Szatkowski <bulislaw@linux.com>
Fri, 1 Oct 2010 08:05:44 +0000 (10:05 +0200)
committerBartosz Szatkowski <bulislaw@linux.com>
Fri, 1 Oct 2010 08:05:44 +0000 (10:05 +0200)
src/plugins/xdxf/DownloadDict.h
src/plugins/xdxf/XdxfDictDownloader.cpp
src/plugins/xdxf/XdxfDictDownloader.h

index c56a769..4b74d67 100644 (file)
@@ -1,12 +1,53 @@
+/*******************************************************************************
+
+    This file is part of mDictionary.
+
+    mDictionary is free software: you can redistribute it and/or modify
+    it under the terms of the GNU General Public License as published by
+    the Free Software Foundation, either version 3 of the License, or
+    (at your option) any later version.
+
+    mDictionary is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU General Public License for more details.
+
+    You should have received a copy of the GNU General Public License
+    along with mDictionary.  If not, see <http://www.gnu.org/licenses/>.
+
+    Copyright 2010 Comarch S.A.
+
+*******************************************************************************/
+
+/*! \file DownloadDict.h
+\brief Represenation of dictionary html entry on XDXF webpage
+
+\author Bartosz Szatkowski <bulislaw@linux.com>
+*/
+
 #ifndef DOWNLOADDICT_H
 #define DOWNLOADDICT_H
 
 #include <QRegExp>
 #include <QStringList>
 
+/**
+    Each dictionary is representing as one html line at XDXF webpage,
+    each entry contains lang from, lang to, file name, file size, link, etc info
+    about dictionary. DownloadDict cut this description and then it may be
+    presented to the user and downloaded
+*/
 class DownloadDict
 {
 public:
+
+    /** Cuts html entry to class
+
+    Html entry looks like <tr><td>...</td><td>...</tr> some of the fields
+    dosn't matters for now so Iam ignoring it.
+
+    \param html html entry (line describing a dict) to be cut
+    */
     DownloadDict(QString html) {
         QRegExp reg("<td.*>(.*)</td>");
         reg.setMinimal(true);
@@ -20,18 +61,29 @@ public:
         _to = tmp.at(7);
         _title = tmp.at(1);
         _size = tmp.at(3);
-        QRegExp lreg("href=\"(.*)\"");
+
+        QRegExp lreg("href=\"(.*)\""); // Cutting link to file
         lreg.setMinimal(true);
         lreg.indexIn(tmp.at(2));
         _link = lreg.capturedTexts().at(1);
     }
 
+    //! \return dictionary source language
     QString fromLang() const {return _from;}
+
+    //! \return dictionary destination language
     QString toLang() const {return _to;}
+
+    //! \return dictionary title
     QString title() const {return _title;}
+
+    //! \return dictionary archive size
     QString size() const {return _size;}
+
+    //! \return link to dictionary archive
     QString link() const {return _link;}
 
+    //! Compares dict by from lang then to lang \return 1 if this is before other
     bool operator <(DownloadDict other) const {
         if(_from < other.fromLang()) return true;
         if(_from > other.fromLang()) return false;
index d5ce72b..a0f6376 100644 (file)
@@ -64,8 +64,12 @@ void XdxfDictDownloader::processFinished(int exitcode) {
 }
 
 void XdxfDictDownloader::downloadComplete() {
+    // Downloaded tar file name is different than extracted folder so we need
+    // some clean directory to identify extracted files
     QDir dir("/tmp/mdict");
     QString dictDirName = dir.entryList().at(2);
+
+    // Dict is in /tmp/mdict/<extracted directory>/dict.xdxf
     QFile dictFile("/tmp/mdict/" + dictDirName + "/dict.xdxf");
     dictFile.copy(QDir::homePath() + "/.mdictionary/" + dictDirName + ".xdxf");
     QFile::remove("/tmp/" + _fileName);
@@ -82,11 +86,15 @@ void XdxfDictDownloader::dictListReceived(QNetworkReply *reply) {
     progressDialog->accept();
     delete progressDialog;
     QString page(QString::fromUtf8(reply->readAll()));
+
+    // You can look at http://xdxf.revdanica.com/down/, we need to get table
+    // with dictionaries entries following regexp match its begining
     QRegExp regOuter("<td>Icon</td><td>Name</td><td>Archive filename</td><td>Archive file size</td><td>Dict file size</td><td>Number of articles</td><td>From</td><td>To</td><td>Submitted by</td><td>Submition date</td></tr>(.*)</table>");
     regOuter.setMinimal(true);
     if(!regOuter.indexIn(page))
         return;
 
+    // Cutting each entry and creating coresponded DownloadDict object
     page = regOuter.capturedTexts().at(1);
     QRegExp regInner("<tr>.*</tr>");
     regInner.setMinimal(true);
@@ -107,9 +115,20 @@ void XdxfDictDownloader::dictListReceived(QNetworkReply *reply) {
 
         _fileName = url.split('/').last();
 
+        // Now its the tricky part ... its temporary (probably)
+        // We dont have any tar-dev and bz2-dev packages on maemo so we need
+        // to call commands via shell, each command from list is called after
+        // previous call returns 0
+
         commands.clear();
         commands.push_back("rm -rf /tmp/mdict");
         commands.push_back("mkdir /tmp/mdict");
+
+        // Downloading xdxf dict from sourceforge is kind of complicated,
+        // there is a lot of redirection and QNetwork* is kind of lost, we
+        // tried to follow redirection (by hand) but we end up with some
+        // page and js scripts and thats all
+        // Maybe calling wget is not pretty one but its working!
         commands.push_back("wget --quiet -P /tmp/ " + url);
         commands.push_back(QString("tar -xjvf /tmp/") + _fileName + QString(" -C /tmp/mdict"));
 
index 3f16509..5968371 100644 (file)
 #include <DownloadDict.h>
 #include "XdxfDictDownloadProgressDialog.h"
 
+/** XdxfDictDownloader is responsible for getting dict list from XDXF website
+    and other actions necessary to download and add dictionary
+
+    When user want to add dictionary he may choose "browse" or "download",
+    after selecting "download"  XDXFDictDownloader would present him list of
+    dictionaries and when he select one downloading would be started. Next
+    step is to extract archive and move file to ~/.mdictionary
+*/
 class XdxfDictDownloader : public QObject {
     Q_OBJECT
 public:
     XdxfDictDownloader(QObject *parent = 0);
+    //! \return name of downloaded file
     QString downloadedFile();
 
 public Q_SLOTS:
+    //! downloads dictionaries list from xdxf website
     void download(QWidget* parent);
 
 Q_SIGNALS:
+    //! emmited when file download precess is complete
     void fileDownloaded(QString);
 
 private Q_SLOTS: