---------------------------------------------------------
 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. KexiWindow ???

#TODO

2. Directories

plugins/<subdirs>
 any plugins such as table/query/form designers, import plugins, one subdirectory per plugin

widgets/<subdirs>
 general-purpose widgets

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
- 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:
};

}
