[bt-devel] Doxygen

[Olaf Radicke]

On Mon, Jul 19, 2010 at 09:45:58PM -0700, Gary Holmlund wrote:
> On 07/19/2010 04:19 PM, Jaak Ristioja wrote:
> >On 19.07.2010 22:32, Gary Holmlund wrote:
> >>I am not a Doxygen expert so any suggestions are quite welcome.
> >We already have a Doxyfile in docs/ which you could use for Doxygen. It is tuned to
> >generate a lot of documentation.
> >
> >Regards,
> >Jaak
> Jaak,
> 
> Thanks. I am now using that Doxygen, except that I turned on
> collaboration diagrams. They look useful, but they are visually very
> large. I am not sure how much they really help.


german: Das Diagramm ist nicht zu lesen, weil der Code nicht zu lesen Ist. 
english: the diagram is confused because, the code is confused.

german: Ich suche schon seid Tagen die Stelle im Code, die den Text von SWord 
holt und im Fenster darstellt. Das ist wohl die Kernfunktion von BibleTime. 
Aber das ist echt nicht so leicht!

english: some tady, i search the text area in the code, which display 
SWord-Text.

german: Hier meine Odyssee durch den Code...
english: Here my odyssey in the code...

// start in file /src/main.cpp:

[...]

int main(int argc, char* argv[]) {

[...]

    BibleTime *mainWindow = new BibleTime();


// go to /src/bibletime.cpp
// german: warum ist die Datei nicht unterhalb von /src/frontend/ ?
// english: why the file is not in /src/frontend/ ?

[...]

BibleTime::BibleTime(QWidget *parent, Qt::WindowFlags flags)
    : QMainWindow(parent, flags), m_WindowWasMaximizedBeforeFullScreen(false)
{

[...]

    QSplashScreen splash;

// german: WAS? BibleTime hat von QMainWindow geerbt. Ein SplashScreen wird als 
// erstes gestartet und nicht von MainWindow. Das ist unsinnig.
// english: SplashScreen is a init-window, so is not good idea, start this
// in a MainWindow-Class.

[...]

    initBackends();

// german: Hä? Das Backend wird in der GUI initziert? 
// english: the GUI starting the backand-init?  

[...]
    initView();

// german: Wo ist "initView()"?
// english: where is "initView()"?
// go to /src/bibletime_init.cpp:

[...]

void BibleTime::initView() {

[...]

void BibleTime::initSwordConfigFile() {

// german: SwordConfig ist kein Teil von MainWindow. Das ist der Grund warum 
// bibletime.cpp zu groß ist und auf mehrere Dateien aufgeteilt werden muss. 
// Die Klasse tut Dinge, die sie nichts angeht. Das ist das Problem.
// english: if the class make only their owen job, then her in not so largely.

[...]

void BibleTime::initBackends() 

// german: Gleiches Problem wie "initSwordConfigFile()"
// english: same problem as  "initSwordConfigFile()"

[...]
    m_mdi = new CMDIArea(this);
    setCentralWidget(m_mdi);

// Okay, was ich suchen muss, ist ein "CMDIArea"
// go to /src/frontend/cmdiarea.cpp:

[...]
QMdiSubWindow* CMDIArea::addSubWindow(QWidget * widget, Qt::WindowFlags windowFlags) {

// german: Wer ruft diese Funktion auf? 
// english: Who calls this function?
// Springe zurück zu /src/bibletime.cpp:

[...]
CDisplayWindow* BibleTime::createReadDisplayWindow(QList<CSwordModuleInfo*> modules, const QString& key) {
[...]
    CDisplayWindow* displayWindow = CDisplayWindowFactory::createReadInstance(modules, m_mdi);
    if ( displayWindow ) {
        displayWindow->init();
	m_mdi->addSubWindow(displayWindow); 

// go to frontend/displaywindow/cdisplaywindowfactory.h:
[...]
    public:
        static CReadWindow* createReadInstance(QList<CSwordModuleInfo*> modules, CMDIArea* parent);

// german: Hä? Die Funktion gibt "CReadWindow*" zurück und nicht 
// "CDisplayWindow*".
// english: the function is returns "CReadWindow*" and not "CDisplayWindow*"?
// go to /src/frontend/displaywindow/cdisplaywindow.h:
// german: Ich sehe jede menge inlines und virtuals. 
// Scheint wohl eine Basisklasse zu sein.
// go to /src/frontend/displaywindow/cdisplaywindow.cpp:

[...]
bool CDisplayWindow::init() {

// german: Kein Textfeld zu sehen.  Suche wer von CDisplayWindow erbt. 
// english: cannot found a text area...
// go to /src/frontend/displaywindow/creadwindow.h:

[...]

class CReadWindow : public CDisplayWindow  {

// german: Ich kann keine andere Klasse finden, die von CDisplayWindow 
// erbt. Also was soll das komplexe Konstrukt? Das riecht schwer nach Ärger!
// Und ich sehe wieder jede menge virtuals, aber kein Textfeld. Also wer
// erbt jetzt wieder von  "CReadWindow"? Warum heißt die Klasse überhaupt
// "Read"? Was wird denn gelesen?
// english: which is "read"? only CReadWindow is inherit from CDisplayWindow.
// so what?
// go to /src/frontend/displaywindow/clexiconreadwindow.h:

[..]

class CLexiconReadWindow : public CReadWindow  {

// german: ...Okay, was für ein Lexikon? Ich kann kein Textfeld finden.
// Und keine andere Klasse scheint von CReadWindow zu erben.
// english: the same with CLexiconReadWindow. And which "Lexicon" is meant?
// go to zu /src/frontend/displaywindow/cbiblereadwindow.h

[...]

class CBibleReadWindow : public CLexiconReadWindow  {

// go to /src/frontend/displaywindow/cbookreadwindow.h:

[...]

class CBookReadWindow : public CLexiconReadWindow  {

// german: Ein Lexikon ist ein Buch, aber ein Bucht ist nicht immer ein Lexikon.
// Warum erbt "CBookReadWindow" von "CLexiconReadWindow"???
// english: a Lexicon is a book, but a book is not always a Lexicon. So
// why book is inherit from Lexicon?

// go to /src/frontend/displaywindow/ccommentaryreadwindow.h:

[...]

class CCommentaryReadWindow : public CLexiconReadWindow  {

// german: Ein Kommentar ist keine Spezialisierung eines Lexikon. Ein
// "Biblelexikon" ist eine Ableitung/Spezialisierung und könnte
// von "Lexikon" erben, aber ein Kommentar?
// english: same inherit confused.
// go back to /src/frontend/displaywindow/cbiblereadwindow.h
// german: Ich kann kein Textfeld entdeken.
// english: cannot found a text area...
// go back to /src/frontend/displaywindow/cbiblereadwindow.cpp

[...]

void CBibleReadWindow::nextBook() {
    if (verseKey()->next(CSwordVerseKey::UseBook)) {
        keyChooser()->setKey(key());
    }
}

// german: Die Klasse hat keine Methode "keyChooser()". 
// english: this class have not a function "keyChooser()".
// go back to base class /src/frontend/displaywindow/clexiconreadwindow.h:
// german: Die Klasse hat keine Methode "keyChooser()". 
// english: this class have not a function "keyChooser()".
// go back to base class /src/frontend/displaywindow/creadwindow.h:
// german: Auch diese Klasse hat keine Methode "keyChooser()".
// english: this class have not a function "keyChooser()" too.
// go back to /src/frontend/displaywindow/cdisplaywindow.h:

[...]

        /** Returns the keychooser widget of this display window. */
        inline CKeyChooser *keyChooser() const {
            return m_keyChooser;
        }

[...]

        CKeyChooser* m_keyChooser;

// go to /src/frontend/keychooser/ckeychooser.h:
// german: Wieder jede menge virtuals. Es wird also wieder vererbt.
// go to /src/frontend/keychooser/ckeychooser.h:

[...]

class CLexiconKeyChooser : public CKeyChooser {

// and /src/frontend/keychooser/versekeychooser/cbiblekeychooser.h:
// and /src/frontend/keychooser/cbooktreechooser.h

// german: Das hält man ja im Kopf nicht aus. Wer soll den bitte aus dem
// Spagetti-Code schlau werden?
// english:  ... i to cark it.  

greeting

Olaf Radicke