--- a/kernel/eka/include/e32ktran.h	Thu Aug 19 11:14:22 2010 +0300
+++ b/kernel/eka/include/e32ktran.h	Tue Aug 31 16:34:26 2010 +0300
@@ -1,4 +1,4 @@
-// Copyright (c) 1995-2009 Nokia Corporation and/or its subsidiary(-ies).
+// Copyright (c) 1995-2010 Nokia Corporation and/or its subsidiary(-ies).
 // All rights reserved.
 // This component and the accompanying materials are made available
 // under the terms of the License "Eclipse Public License v1.0"
@@ -28,37 +28,68 @@
 #include <e32std.h>
 #include <e32keys.h>
 #include <e32base.h>
-//
+
+/**
+Represents a specific combination of modifier
+keys.
+
+The definition will match a given a key combination
+bitfield, if when anded with the mask iMask, it equals
+iValue. Bitfields are made up of bits defined in TEventModifier.
+
+eg. to match Ctrl and Shift and not Fn modifiers
+
+iMask = EModifierShift | EModifierCtrl | EModifierFunc
+iValue = EModifierShift | EModifierCtrl
+*/
 class TMaskedModifiers
 	{
 public:
-	TUint iMask;
-	TUint iValue;
+	TUint iMask; //!< Mask to be binary anded with some value
+	TUint iValue; //!< Must match the masked bitfield
 	};
-//
+
+/**
+Defines different match types to be used
+in TKeyCodePattern
+*/
 enum TPattern
 	{
-	EAnyKey=0x00,
-	EAnyAlphaNumeric,
-	EAnyAlpha,
-	EAnyAlphaLowerCase,
-	EAnyAlphaUpperCase,
-	EAnyDecimalDigit,
+	EAnyKey=0x00, ///< match any key
+	EAnyAlphaNumeric, ///< match any alpha or numeric key
+	EAnyAlpha, ///< match any alpha key
+	EAnyAlphaLowerCase, ///< match any lower-case key
+	EAnyAlphaUpperCase, ///< match any upper-case key
+	EAnyDecimalDigit, ///< match any decimal digit
 	EAnyDigitGivenRadix,
-	EAnyModifierKey,
-	EMatchKey=0x40,
-	EMatchKeyCaseInsens,
-	EMatchLeftOrRight
+	EAnyModifierKey, ///< match any modifier key (e.g. alt, fn, ctrl)
+	EMatchKey=0x40, ///< match if equal to keycode value in first field
+	EMatchKeyCaseInsens, ///< like EMatchKey but perform case-insensitive comparison
+	EMatchLeftOrRight ///< match if equal to keycode value or (keycode value + 1)
 	};
-//
+
+/**
+Defines a keypress using one of the match types defined in TPattern
+and possibly a reference scan code. It is possible to specify generic
+or specific keypresses eg. any decimal digit, or a particular
+key, matched case insensitively.
+
+@see TPattern
+*/
 class TKeyCodePattern
 	{
 public:
-	TUint16 iKeyCode;
-	TInt8   iPattern;
+	TUint16 iKeyCode; ///< Reference scancode, used when iPattern is EMatchKey, EMatchKeyCaseInsens, or EMatchLeftOrRight
+	TInt8   iPattern; ///< Comparison, of type TPattern
 	TInt8   iFiller;
 	};
-//
+
+/**
+A Capture Key is a special key or key combination which should be
+sent to a specific window-group, instead of the currently
+active window. For example a camera application might request that
+camera button events always be sent to it.
+*/
 class TCaptureKey
 	{
 public:
@@ -67,7 +98,10 @@
 	TUint iApp;
 	TUint iHandle;
 	};
-//
+
+/**
+Used by CKeyTranslator to return translation results.
+*/
 class TKeyData
 	{
 public:
@@ -77,7 +111,12 @@
 	TBool iIsCaptureKey;
 	TUint iKeyCode;
 	};
-//
+
+/**
+A set of TCaptureKey objects which is passed to a CKeyTranslator
+when translating key events. This is so it can indicate if a
+translated key event should be treated as a special Capture Key.
+*/
 class CCaptureKeys: public CBase
 	{
 public:
@@ -93,11 +132,19 @@
 	IMPORT_C void ProcessCaptureKeys(TKeyData &aKeyData) const;
 protected:
 	void CheckCaptureKey(const TCaptureKey &aCaptureKey);
-	void removeCaptureKey(TUint index);
 protected:
 	RArray<TCaptureKey> iCKarray;
 	};
-//
+
+/**
+A CKeyTranslator derived object will be created by the window server
+in order to translate key scancode data, contained in a TRawEvent, in to
+generic logical key press, as defined in TKeyCode. Essentially, these
+translations
+
+The translator object will perform the actual lookups using data from
+a platform specific keymap DLL, conventionally named ekdata.dll.
+*/
 class CKeyTranslator: public CBase
 	{
 public: