---------------------------------------------------------
 Kexi Naming Conventions
 
 These rules apply to Kexi Team developers
 There are also guidelines for future naming decissions.
 
 Started: 2003-10-17
 Copyright (C) 2003 Kexi Team
 Kexi home page: http://www.kexi-project.org/
---------------------------------------------------

1. Namespaces
To simplify class names and make these names shorter, we use namespaces.

1.1. KexiDB namespace

This denotes KexiDB module. All classes from kexidb/ directory are in KexiDB 
namespace.KexiDB-compatible database drivers (from kexidb/drivers/ 
subdirectories are not in this KexiDB namespace.


1.2. KexiWindow ???

#TODO

2. Directories

plugins/<subdirs>
 any plugins like Kexi dialogs for table altering, query desinger, etc.;
 one subdirectory per plugin; each subdirectory is a KDE module
 
widgets/<subdirs>
 any widgets that are not dependent on core nor kexidb, thus reusable 
 in other projects; one subdirectory per widget; all subdirectories are linked 
 together with static compilation to single common library

3rdparty/<subdirs>
 any modules that can be considered as external (not necessarily optional)

 
3. Creating documentation

- Doxygen (www.doxygen.org) is used for generating Kexi developer documentation.
- default target directory of these docs in html format is: doc/html for all sources
  and doc/kexidb/html for kexidb-only docs
- one step (..) up from mentioned dirs are places for .doxygen project files used
  for docs generating 
- Single-line comments are created begginning with: //!
- Multi-line comments are created begginning with /*! or /**
- Style of comments (/*! of /**) for given file should be preserved

Example 3.1: Comments for non-void functions, adding information about parameters:

/*! Displays value of \a x. 
 \return true if displaying is successfull */
bool display(int x);

Notes for example:  
-\return special Doxygen's  tag is used to describe that we return 
something in the method (\returns will not work for Doxygen!). 
-Clause should be started from capital letter and terminated with a dot.
-"\a" special tag should be used before inserting argument names (names are 
equal to these from the method's definition) - the names will be therefore
highlighted by Doxygen.

-For more sophisticated methods (with more arguments), you can as well 
use \param tag, e.g.:

/*!
\param x horizontal position
\param y vertical position
\param col color of the box
*/

-Methods/functions should be documented in header files (.h), not in implementation
 files. This allows easier inspection for users of the source code.
-Comments from implementation files can be turned into 
 additional documentation, if really needed (when we use "/*!") 
 and this also will be included to generated docs if Doxygen project has enabled appropriate 
 option for doing this.
-Classes should be also documented -comments put just as the lines 
 before "class keyword.

-to add reference to similar or related function, use \sa tag, e.g.:
/*! blablabla
 \sa bleble
*/

-to mark a code fragment that someting is TO DO, you can use \todo tag, e.g.:

/*! \todo (js) it is so hard to implement!
*/

-example above shows that adding e.g. own nick inside the brackets what can help 
to recognise who marked given fragment.

4. Indentation
4.1 We use 2-spaces indentation. Do not use tabs.
example:
	QString		objectName(); //wrong
  QString objectName(); //ok

Rule: don't use many spaces or tabs between words.

4.2 To avoid many indentation levels, we can use:

void mymethod()
{
  if (!something)
    return;
  if (!something_else && .....)
    return;
  do_something();
}

 instead of:

void mymethod()
{
	if (something) {
		if(something_else && .....) {
			do_something;
		}
	}
}

This is good, because made qt and kde sources readable.

4.3 Indentation within classes declaration

namespace MyNamespace {

class MyClass {
  public:
    MyClass();
    void method();
  protected:
};

}
