FileBrowser: Add helpful comments

include/FileBrowser.h

@@ -48,6 +48,14 @@ class FileBrowser : public SideBarWidget
 {
 	Q_OBJECT
 public:
+	/**
+		Create a file browser side bar widget
+		@param directories '*'-separated list of directories to search for.
+			If a directory of factory files should be in the list it
+			must be the last one (for the factory files delimiter to work)
+		@param filter Filter as used in QDir::match
+		@param recurse *to be documented*
+	*/
 	FileBrowser( const QString & directories, const QString & filter,
 			const QString & title, const QPixmap & pm,
 			QWidget * parent, bool dirs_as_items = false, bool recurse = false );
@@ -69,8 +77,8 @@ private:
 
 	QLineEdit * m_filterEdit;
 
-	QString m_directories;
-	QString m_filter;
+	QString m_directories; //!< Directories to search, split with '*'
+	QString m_filter; //!< Filter as used in QDir::match()
 
 	bool m_dirsAsItems;
 	bool m_recurse;
@@ -159,7 +167,14 @@ private:
 	static QPixmap * s_folderOpenedPixmap;
 	static QPixmap * s_folderLockedPixmap;
 
+	//! Directories that lead here
+	//! Initially, this is just set to the current path of a directory
+	//! If, however, you have e.g. 'TripleOscillator/xyz' in two of the
+	//! file browser's search directories 'a' and 'b', this will have two
+	//! entries 'a/TripleOscillator' and 'b/TripleOscillator'
+	//! and 'xyz' in the tree widget
 	QStringList m_directories;
+	//! Filter as used in QDir::match()
 	QString m_filter;
 
 	int m_dirCount;

src/gui/FileBrowser.cpp

@@ -232,6 +232,7 @@ void FileBrowser::addItems(const QString & path )
 		return;
 	}
 
+	// try to add all directories from file system alphabetically into the tree
 	QDir cdir( path );
 	QStringList files = cdir.entryList( QDir::Dirs, QDir::Name );
 	for( QStringList::const_iterator it = files.constBegin();
@@ -247,6 +248,7 @@ void FileBrowser::addItems(const QString & path )
 						m_l->topLevelItem( i ) );
 				if( d == NULL || cur_file < d->text( 0 ) )
 				{
+					// insert before item, we're done
 					Directory *dd = new Directory( cur_file, path,
 												   m_filter );
 					m_l->insertTopLevelItem( i,dd );
@@ -256,6 +258,11 @@ void FileBrowser::addItems(const QString & path )
 				}
 				else if( cur_file == d->text( 0 ) )
 				{
+					// imagine we have subdirs named "TripleOscillator/xyz" in
+					// two directories from m_directories
+					// then only add one tree widget for both
+					// so we don't add a new Directory - we just
+					// add the path to the current directory
 					d->addDirectory( path );
 					d->update();
 					orphan = false;
@@ -264,6 +271,8 @@ void FileBrowser::addItems(const QString & path )
 			}
 			if( orphan )
 			{
+				// it has not yet been added yet, so it's (lexically)
+				// larger than all other dirs => append it at the bottom
 				Directory *d = new Directory( cur_file,
 											  path, m_filter );
 				d->update();
@@ -761,6 +770,7 @@ void Directory::update( void )
 	if( !childCount() )
 	{
 		m_dirCount = 0;
+		// for all paths leading here, add their items
 		for( QStringList::iterator it = m_directories.begin();
 					it != m_directories.end(); ++it )
 		{
@@ -796,6 +806,7 @@ bool Directory::addItems(const QString & path )
 
 	bool added_something = false;
 
+	// try to add all directories from file system alphabetically into the tree
 	QStringList files = thisDir.entryList( QDir::Dirs, QDir::Name );
 	for( QStringList::const_iterator it = files.constBegin();
 						it != files.constEnd(); ++it )
@@ -810,6 +821,7 @@ bool Directory::addItems(const QString & path )
 								child( i ) );
 				if( d == NULL || cur_file < d->text( 0 ) )
 				{
+					// insert before item, we're done
 					insertChild( i, new Directory( cur_file,
 							path, m_filter ) );
 					orphan = false;
@@ -818,6 +830,12 @@ bool Directory::addItems(const QString & path )
 				}
 				else if( cur_file == d->text( 0 ) )
 				{
+					// imagine we have top-level subdirs named "TripleOscillator" in
+					// two directories from FileBrowser::m_directories
+					// and imagine both have a sub folder named "xyz"
+					// then only add one tree widget for both
+					// so we don't add a new Directory - we just
+					// add the path to the current directory
 					d->addDirectory( path );
 					orphan = false;
 					break;
@@ -825,6 +843,8 @@ bool Directory::addItems(const QString & path )
 			}
 			if( orphan )
 			{
+				// it has not yet been added yet, so it's (lexically)
+				// larger than all other dirs => append it at the bottom
 				addChild( new Directory( cur_file, path,
 								m_filter ) );
 				m_dirCount++;