New IDL API, extensions to basic at-spi interfaces.

Also added some enhancements to event emission - events
now include host-app, role, and accessible-name info.
(This commit is a preventative measure to ensure that
the new stuff appears in gnome 2.13 tarballs today;
ChangeLog entry will be completed later today.)


git-svn-id: http://svn.gnome.org/svn/at-spi/trunk@782 e2bd861d-eb25-0410-b326-f6ed22b6b98c

21 files changed, 2270 insertions, 394 deletions

diff --git a/idl/Accessibility.idl b/idl/Accessibility.idl
index 990324a9..63ff91dc 100644
--- a/idl/Accessibility.idl
+++ b/idl/Accessibility.idl
@@ -2,7 +2,7 @@
  * AT-SPI - Assistive Technology Service Provider Interface 
  * (Gnome Accessibility Project; http://developer.gnome.org/projects/gap)
  *
- * Copyright 2001 Ximian, Inc.
+ * Copyright 2001-2005 Ximian, Inc. and Sun Microsystems, Inc.
  *
  * This library is free software; you can redistribute it and/or
  * modify it under the terms of the GNU Library General Public
@@ -32,6 +32,67 @@
 #endif
 #endif
 
+#ifndef _BONOBO_IDL_INCLUDED_
+#define _BONOBO_IDL_INCLUDED_
+#include <Bonobo_Unknown.idl>
+#endif /* _BONOBO_IDL_INCLUDED_ */
+
+/*!\mainpage AT-SPI Interfaces and Subinterfaces
+ *
+ * This is the main documentation page for the 
+ * Assistive Technology Service Provider Interface (AT-SPI). 
+ * 
+ * \section apps Applications and Interface Components
+ * Namespace Accessibility includes service APIs implemented by
+ * participating applications and their user interface components:\n\n
+ * Accessibility::Accessible\n 
+ * Accessibility::Application\n
+ * Accessibility::Desktop\n
+ * Accessibility::Component\n
+ * Accessibility::Hypertext\n
+ * Accessibility::Image\n
+ * Accessibility::Selection\n
+ * Accessibility::StreamableContent\n
+ * Accessibility::Table\n
+ * Accessibility::Text\n
+ * Accessibility::EditableText\n
+ * Accessibility::Value
+ *
+ * \section types Enumerated Types
+ * Accessibility defines a number of key enumerated types, including:\n\n
+ * Accessibility::RelationType\n
+ * Accessibility::Role\n
+ * Accessibility::StateType\n
+ * Accessibility::Event\n
+ * Accessibility::EventDetails \n
+ *
+ * \section Registry
+ * Accessibility also includes Accessibility::Registry,
+ * which is the service used by assistive technologies and related
+ * AT-SPI clients to register interest in certain classes of events,
+ * enumerate the currently available desktop and application list,
+ * and to synthesize certain kinds of device events.
+ *
+ * \section listeners Event Listener Interfaces
+ * Accessibility::EventListener\n
+ * Accessibility::DeviceEventListener
+ *
+ * \section helpers Helper Interfaces
+ *
+ * The following interfaces may be implemented by assistive technologies 
+ * themselves, in order to export their services in a consistent manner or
+ * in order to interoperate with other applications or desktop services.\n
+ *
+ * Accessibility::LoginHelper : Implemented by adaptive technologies which 
+ * need to participate in user-authentication or login activities, and which
+ * therefore may need negotiation with authentication agents or processes.\n
+ *
+ * Accessibility::Selector [NEW]: Implemented by user agents or assistive 
+ * technologies which export lists of choices from which the end-user is 
+ * expected to make selections.  Useful for various types of remote
+ * activation or intercommunication between multiple ATs.
+ **/
+
 /*
  * Accessibility interfaces and subinterfaces
  */
@@ -64,6 +125,8 @@
 #include <Accessibility_Event.idl>
 #include <Accessibility_Registry.idl>
 #include <Accessibility_Role.idl>
+#include <Accessibility_LoginHelper.idl>
+#include <Accessibility_Selector.idl>
 
 #ifndef __ACCESSIBILITY_COMPILATION__
 #ifdef  __ORBIT_IDL__
diff --git a/idl/Accessibility_Accessible.idl b/idl/Accessibility_Accessible.idl
index d9bccd9b..ac56f68f 100644
--- a/idl/Accessibility_Accessible.idl
+++ b/idl/Accessibility_Accessible.idl
@@ -23,120 +23,251 @@
 #ifndef _ACCESSIBILITY_ACCESSIBLE_IDL
 #define _ACCESSIBILITY_ACCESSIBLE_IDL
 
-#include <Bonobo_Unknown.idl>
-
 #include "Accessibility_Relation.idl"
 #include "Accessibility_State.idl"
 #include "Accessibility_Role.idl"
 
 module Accessibility {
   
+  /** used by Text and Document: these correspond to the POSIX setlocale() enum values. **/
+  enum LOCALE_TYPE {
+      LOCALE_TYPE_MESSAGES,
+      LOCALE_TYPE_COLLATE,
+      LOCALE_TYPE_CTYPE,
+      LOCALE_TYPE_MONETARY,
+      LOCALE_TYPE_NUMERIC,
+      LOCALE_TYPE_TIME
+  };
+
+    /** A list of Relations, which may be many-to-many. */
   typedef sequence<Relation> RelationSet;
 
+    /** 
+     * A list of name-value pairs, returned as a sequence of strings; 
+     * the name and value are separated by a colon. 
+     * @note "Attributes" returned in AttributeSet lists are distinct from, 
+     * and should not be confused with, "attribute" members of interfaces
+     * as defined by the IDL "attribute" keyword.  IDL attributes are
+     * strongly-typed values which are individually obtained via
+     * language-specific bindings whose syntax is dictated by the OMG's
+     * IDL language bindings.  For instance using the C language,
+     * the "Accessible::name" attribute is queried using
+     * \c Accessibility_Accessible__get_name (obj, &ev);
+     * Name-value pairs associated with Accessible instances are not
+     * normally redundant with these IDL attributes, i.e. there is no
+     * "accessible-name" attribute in the AttributeSet returned from
+     * Accessible::getAttributes().
+     *
+     * Where possible, the names and values in the name-value pairs
+     * should be chosen from well-established attribute namespaces
+     * using standard semantics.  For example, metadata namespace and
+     * values should be chosen from the 'Dublin Core' Metadata
+     * namespace using Dublin Core semantics:
+     * http://dublincore.org/dcregistry/
+     * Similarly, relevant structural metadata should be exposed
+     * using attribute names and values chosen from the CSS2 and WICD specification:
+     * http://www.w3.org/TR/1998/REC-CSS2-19980512
+     * WICD (http://www.w3.org/TR/2005/WD-WICD-20051121/).
+     * 
+     * Finally, note that typographic, semantic, and presentational annotations which
+     * are associated with text content, in particular which are associated with particular
+     * text ranges, should be exposed via Accessibility::Text::getAttributeRun instead of
+     * via these more general 'Object attributes'.
+     *
+     * @since AT-SPI 1.7.0
+     */
+  typedef sequence<string> AttributeSet;
+
+    /** 
+     * A list of accessible roles 
+     * @since AT-SPI 1.7.0
+     **/
+  typedef sequence<Role> RoleSet;
+
+    /** Used by Component and Text, a struct defining a bounding rectangle. 
+     * The relevant coordinate system is determined by the context of the
+     * API call which returned or receives the value.
+     */
   struct BoundingBox {
-	  long x;
-	  long y;
-	  long width;
-	  long height;
+          long x; /**< the value corresponding to the minimum or leftmost x position. */
+          long y; /**< the value corresponding to the minimum y value.  */
+          long width; /**< the horizontal extent of the bounding box,
+		       * that is, the difference between the maximum and minimum
+		       * x coordinate bounds.
+		       */
+          long height; /**< the vertical extent of the bounding box, 
+			* that is, the difference between the maximum and minimum
+			* y coordinate bounds.
+			*/
   };
 
+    
+  interface Application; /**< defined in Accessibility_Application.idl **/
+
+  /** 
+   * The base interface which is implemented by all accessible objects. 
+   * All objects support interfaces for querying their contained 'children' 
+   * and position in the accessible-object hierarchy, whether or not they
+   * actually have children.
+   *
+   * @note Events that may be emitted by instances of Accessible include:
+   * \li \c "object:property-change" A base (strongly-typed) object attribute has changed,
+   *         for instance "object:property-change:accessible-name".
+   *         Notifed property subtypes include accessible-name, accessible-description,
+   *         and accessible-parent. 
+   *
+   * \li \c "object:children-changed" The number or identity of an object's children
+   *         has changed.
+   * \li \c "object:state-changed" The object's StateSet has had a state added
+   *         or removed.
+   * \li \c "object:active-descendant-changed" If the object includes 
+   *         STATE_MANAGES_DESCENDANTS, this event is fired to indicate that the 
+   *         descendant having STATE_ACTIVE has changed; this corresponds to
+   *         "micro" keyboard focus when the containing/emitting object has
+   *         "macro" or technical keyboard focus.  For instance, this event is
+   *         usually emitted while traversing tables and/or spreadsheet cells.
+   * \li \c "object:attribute-change" A weakly-typed property, as contained in the
+   *         AttributeSet returned by Accessible::getAttributes, has changed in value,
+   *         been added, or been removed from the object.
+   *         ("object:attribute-change" notifications were added in AT-SPI 1.7.0)
+   */
   interface Accessible : Bonobo::Unknown {
 
     /**
-     * @name: a (short) #string representing the object's name.
+     * a (short) \c string representing the object's name.
      **/
     attribute string name;
 
     /**
-     * @description: a #string describing the object in more detail than @name.
+     * a \c string describing the object in more detail than \a name.
      **/
     attribute string description;
 
     /**
-     * @parent: an #Accessible object which is this object's containing object.
+     * an ::Accessible object which is this object's containing object.
      **/
-    readonly attribute Accessible parent;
+    readonly attribute Accessibility::Accessible parent;
 
     /**
-     * @childCount: the number of children contained by this object.
+     * childCount: the number of children contained by this object.
      **/
     readonly attribute long    	childCount;
 
     /**
-     * isEqual:
-     * @obj: an #Accessible object reference to compare to
-     *
-     * Determine whether an #Accessible refers to the same object as another
+     * Determine whether an ::Accessible refers to the same object as another.
+     * This method should be used rather than brute-force comparison of
+     * object references (i.e. "by-value" comparison), as two object references
+     * may have different apparent values yet refer to the same object.
      *
-     * Returns: a #boolean indicating whether the two object references
+     * @param obj: an ::Accessible object reference to compare to
+     * @returns: a \c boolean indicating whether the two object references
      *         point to the same object. 
      **/
     boolean isEqual (in Accessible obj);
 
     /**
-     * getChildAtIndex:
-     * @index: an in parameter indicating which child is requested (zero-indexed).
-     *
-     * Get the accessible child of this object at index @index.
-     *
-     * Returns: the 'nth' @Accessible child of this object.
+     * Get the accessible child of this object at \c index.
+     * @param index: an in parameter indicating which child is requested (zero-indexed).
+     * @returns: the 'nth' ::Accessible child of this object.
      **/
     Accessible 	getChildAtIndex (in long index);
 
     /**
-     * getIndexInParent:
-     *
      * Get the index of this object in its parent's child list.
-     *
-     * Returns: a long integer indicating this object's index in the parent's list.
+     * @returns: a long integer indicating this object's index in the parent's list.
      **/
     long		getIndexInParent ();
 
     /**
-     * getRelationSet:
-     *
      * Get a set defining this object's relationship to other accessible objects.
-     *
-     * Returns: a @RelationSet defining this object's relationships.
+     * @returns: a ::RelationSet defining this object's relationships.
      **/
     RelationSet	getRelationSet ();
 
     /**
-     * getRole:
-     * Get the @Role indicating the type of UI role played by this object.
+     * Get the ::Role indicating the type of UI role played by this object.
      *
-     * Returns: a @Role indicating the type of UI role played by this object.
+     * @returns: a ::Role indicating the type of UI role played by this object.
      **/
     Role		getRole ();
 
     /**
-     * getRoleName:
      * Get a string indicating the type of UI role played by this object.
      *
-     * Returns: a UTF-8 string indicating the type of UI role played by this object.
+     * @returns: a UTF-8 string indicating the type of UI role played by this object.
      **/
     string		getRoleName ();
 
     /**
-     * getLocalizedRoleName:
      * Get a string indicating the type of UI role played by this object,
      * translated to the current locale.
      *
-     * Returns: a UTF-8 string indicating the type of UI role played by this object.
+     * @returns: a UTF-8 string indicating the type of UI role played by this object.
      **/
     string		getLocalizedRoleName ();
 
     /**
-     * getState:
-     *
-     * Get the current state of the object as a @StateSet.
-     * Returns: a @StateSet encapsulating the currently true states of the object.
+     * Get the current state of the object as a ::StateSet.
+     * @returns: a ::StateSet encapsulating the currently true states of the object.
      **/
     StateSet	getState ();
 
-    void        unImplemented ();
-    void        unImplemented2 ();
-    void        unImplemented3 ();
+    /**
+     * Get a list of properties applied to this object as a whole, as an 
+     * ::AttributeSet consisting of name-value pairs.  As such these attributes
+     * may be considered weakly-typed properties or annotations, as distinct
+     * from the strongly-typed interface instance data declared using the IDL 
+     * "attribute" keyword.
+     *
+     * Not all objects have explicit "name-value pair" AttributeSet properties.  
+     *
+     * Attribute names and values may have any UTF-8 string value, however where possible,
+     * in order to facilitate consistent use and exposure of "attribute" properties by
+     * applications and AT clients, attribute names and values should chosen from  
+     * a publicly-specified namespace where appropriate.
+     *
+     * Where possible, the names and values in the name-value pairs
+     * should be chosen from well-established attribute namespaces
+     * using standard semantics.       
+     * For example, attributes of ::Accessible objects corresponding to XHTML content 
+     * elements should correspond to attribute names and values specified in the w3c 
+     * XHTML specification, at http://www.w3.org/TR/xhtml2, where such values are not 
+     * already exposed via a more strongly-typed aspect of the AT-SPI API.
+     * Metadata names and
+     * values should be chosen from the 'Dublin Core' Metadata
+     * namespace using Dublin Core semantics:
+     * http://dublincore.org/dcregistry/
+     * Similarly, relevant structural metadata should be exposed
+     * using attribute names and values chosen from the CSS2 and WICD specification:
+     * http://www.w3.org/TR/1998/REC-CSS2-19980512
+     * WICD (http://www.w3.org/TR/2005/WD-WICD-20051121/).
+     *
+     * @note Clients seeking semantic or typographical attributes associated with
+     * specific character spans of text content should use ::Text::getAttributeRun instead.
+     * The attributes returned by Accessible::getAttributes do not include
+     * "text attributes".
+     *
+     * @see ::Accessibility::Text::getAttributeRun
+     *
+     * @returns: an ::AttributeSet encapsulating any "attribute values" currently 
+     * defined for the object.
+     *
+     * @since AT-SPI 1.7.0
+     **/
+    AttributeSet	getAttributes ();
+
+    /**
+     * Get the containing Application for this object.
+     *
+     * @returns the Application instance to which this object belongs.
+     * @since AT-SPI 1.7.0
+     **/
+    Application getApplication ();
+
+     /** /cond future expansion */
+     void unimplemented ();
+     /** /endcond */
+
   };
 };
 
diff --git a/idl/Accessibility_Action.idl b/idl/Accessibility_Action.idl
index 2bab51db..d14d90bf 100644
--- a/idl/Accessibility_Action.idl
+++ b/idl/Accessibility_Action.idl
@@ -21,63 +21,78 @@
  */
 
 module Accessibility {
-
+    /**
+     * An interface through which a user-actionable user interface
+     * component can be manipulated.  Components which react to mouse or
+     * keyboard input from the user, (with the exception of pure text entry
+     * fields with no other function), should implement this interface.
+     * Typical actions include "click", "press", "release" (for instance for
+     * buttons), "menu" (for objects which have context menus invokable from 
+     * mouse or keyboard), "open" for icons representing files folders, and others.
+     */
   interface Action : Bonobo::Unknown {
 
     /**
-     * nActions: a @long containing the number of actions this object supports.
+     * nActions: a \c long containing the number of actions this object supports.
      * 
      **/
     readonly attribute long nActions;
 
     /**
      * getDescription:
-     * @index: an %in parameter specifying the index of the action 
+     * @param index: the index of the action 
      *   for which a description is desired.
      *
-     * Gets the description of the specified action.
+     * Get the description of the specified action.  The description of an action
+     * may provide information about the result of action invocation, unlike the
+     * action name.
+     * @see getName.
      *
-     * Returns: a @wstring containing the description of the specified action.
+     * @returns: a \c string containing the description of the specified action.
      *
      **/
     string getDescription (in long index);
 
     /**
      * getName:
-     * @index: an %in parameter specifying the index of the action 
+     * @param index: the index of the action 
      *   whose name is requested.
      *
-     * Gets the name of the specified action.
+     * Get the name of the specified action.  Action names generally describe
+     * the user action, i.e. "click" or "press", rather then the result of 
+     * invoking the action.
      *
-     * Returns: a @string containing the name of the specified action.
+     * @returns: a \c string containing the name of the specified action.
      *
      **/
     string getName (in long index);
 
     /**
      * doAction:
-     * @index: an %in parameter specifying the 0-based index of the action to perform.
+     * @param index: the 0-based index of the action to perform.
      *
      * Causes the object to perform the specified action.
      *
-     * Returns: a @boolean indicating success or failure.
+     * @returns: a \c boolean indicating success or failure.
      *
      **/
     boolean doAction (in long index);
 
     /**
      * getKeyBinding:
-     * @index: an %in parameter specifying the 0-based index of the action 
+     * @param index: the 0-based index of the action 
      *   for which a key binding is requested.
      *
-     * Gets the key binding associated with a specific action.
+     * Get the key binding associated with a specific action.
      *
-     * Returns: a @string containing the key binding for the specified action,
-     *   "" if none exists.
+     * @returns: a \c string containing the key binding for the specified action,
+     *   or an empty string ("") if none exists.
      **/
     string getKeyBinding (in long index);
 
+      
     /**
+     * \cond
      * unImplemented:
      *
      * placeholders for future expansion.
@@ -86,6 +101,7 @@ module Accessibility {
     void unImplemented2 ();
     void unImplemented3 ();
     void unImplemented4 ();
+      /** \endcond */
   };
 };
 
diff --git a/idl/Accessibility_Application.idl b/idl/Accessibility_Application.idl
index 33b4998d..e35332f8 100644
--- a/idl/Accessibility_Application.idl
+++ b/idl/Accessibility_Application.idl
@@ -2,7 +2,7 @@
  * AT-SPI - Assistive Technology Service Provider Interface 
  * (Gnome Accessibility Project; http://developer.gnome.org/projects/gap)
  *
- * Copyright 2001 Sun Microsystems Inc.
+ * Copyright 2001-2004 Sun Microsystems Inc.
  *
  * This library is free software; you can redistribute it and/or
  * modify it under the terms of the GNU Library General Public
@@ -28,102 +28,97 @@
 
 module Accessibility {
 
-  enum LOCALE_TYPE {
-      LOCALE_TYPE_MESSAGES,
-      LOCALE_TYPE_COLLATE,
-      LOCALE_TYPE_CTYPE,
-      LOCALE_TYPE_MONETARY,
-      LOCALE_TYPE_NUMERIC,
-      LOCALE_TYPE_TIME
-  };
-
+  /** 
+   * An interface identifying an object which is the root of the
+   * user interface Accessible hierarchy associated with a running application.
+   * Children of Application are typically, but not exclusively, 
+   * top-level windows.
+   * @note It is possible for an element deeper in an Accessibility stack to
+   * implement Application, for instance in the case of "embedded applications"
+   * which draw into toplevel windows associated with other applications
+   * from the user's point of view.
+   */
   interface Application : Accessible {
 
     /**
-     * @toolkitName:
      * A string indicating the type of user interface toolkit
      * which is used by the application.
-     * Ordinarily clients of @AccessibleApplication should be
-     * toolkit-agnostic, dependencies on this method probably
-     * should be reconsidered!
+     * @note Ordinarily clients of ::Application should be
+     * toolkit-agnostic, dependencies on this property should
+     * be avoided where possible.
      **/
     readonly attribute string toolkitName;
 
     /**
-     * @version:
      * A string indicating the version number of the application's
      * accessibility bridge implementation.
      **/
     readonly attribute string version;
 
     /**
-     * @id:
      * The application instance's unique ID as assigned by the registry.
      **/
     attribute long id;
 
     /**
-     * registerToolkitEventListener:
-     * @listener: an #EventListener object which will receive the requested
+     * @param listener: an ::EventListener object which will receive the requested
      *            events from the application's toolkits via toolit 'bridges'
-     * @eventName: a UTF-8 string indicating the type of (toolkit-specific) event
+     * @param eventName: a UTF-8 string indicating the type of (toolkit-specific) event
      *            being requested.  Not all applications can generate toolkit events of
      *            a given type.
      *
      * Register with this application's toolkit for "toolkit-specific" event notifications.
+     * @note
      *       For most event support, clients should use non-toolkit-specific events
-     *       whenever possible, via #Registry::registerGlobalEventListener - this method 
-     *       is provided as a 'back door' when generic names do not exist for the events in question.
-     * SUBJECT TO DEPRECATION in favor of Registry::registerGlobalEventListener forms.
-     *
+     *       whenever possible, via ::Registry::registerGlobalEventListener - this method 
+     *       is provided as a 'back door' when generic names do not exist for the events in 
+     *       question.
      **/
     void registerToolkitEventListener (in EventListener listener, in string eventName);
 
     /**
      * registerObjectEventListener:
-     * @listener: an #EventListener object which will receive the requested
+     * @param listener: an ::EventListener object which will receive the requested
      *            events
-     * @eventName: a UTF-8 string indicating the type of (toolkit-specific) event
+     * @param eventName: a UTF-8 string indicating the type of (toolkit-specific) event
      *            being requested.  
      * Register with this application toolkit for "Accessibility::Accessible" 
-     * event notifications. SUBJECT TO DEPRECATION
-     *
+     * event notifications. 
+     * @note: SUBJECT TO DEPRECATION.
      **/
     void registerObjectEventListener (in EventListener listener, in string eventName);
 
     /**
-     * pause:
-     *
      * Request that the application temporarily stop sending events.
      * In most cases this should pause the application's main event loop.
      *
-     * Returns: %true if the request succeeded, %false otherwise.
+     * @returns: \c true if the request succeeded, \c false otherwise.
+     *
+     * @note: This method is not implemented in most toolkits, and therefore should be treated with caution.
      **/
     boolean       pause ();
 
     /**
-     * resume:
-     *
      * Request that the application resume sending events.
      *
-     * Returns: %true if the request succeeded, %false otherwise.
+     * @returns: \c True if the request succeeded, \c False otherwise.
      **/
     boolean       resume ();
 
-     /**
-     * getLocale:
-     *
-     * @lctype: the LocaleType for which the locale is queried.
+    /**
      * Gets the locale in which the application is currently operating.
-     * For the current message locale, use @lctype LOCALE_TYPE_MESSAGES.
+     * For the current message locale, use \a lctype LOCALE_TYPE_MESSAGES.
      *
-     * Returns: a string compliant with the POSIX standard for locale description.
+     * @param lctype The LocaleType for which the locale is queried.
+     * @returns a string compliant with the POSIX standard for locale description.
      **/
     string       getLocale (in LOCALE_TYPE lctype);
 
+    /**\cond (This comment tells doxygen not to document these) */
     void          unImplemented_ ();
     void          unImplemented2_ ();
     void          unImplemented3_ ();
+    /**\endcond */
   };
 };
 
diff --git a/idl/Accessibility_Component.idl b/idl/Accessibility_Component.idl
index b444ab1c..f4f063ea 100644
--- a/idl/Accessibility_Component.idl
+++ b/idl/Accessibility_Component.idl
@@ -24,32 +24,140 @@
 
 module Accessibility {
 
+  /** 
+   * The ComponentLayer of a Component instance indicates its relative stacking order
+   * with respect to the onscreen visual representation of the UI.
+   * ComponentLayer, in combination with Component bounds information, can be used
+   * to compute the visibility of all or part of a component.  This is important in
+   * programmatic determination of region-of-interest for magnification, and in
+   * ¨flat screen review¨ models of the screen, as well as for other uses.
+   * Objects residing in two of the ComponentLayer categories support
+   * further z-ordering information, with respect to their peers in the same layer:
+   * namely, LAYER_WINDOW and LAYER_MDI.  Relative stacking order for other objects within
+   * the same layer is not available; the recommended heuristic is ¨first child paints first¨, 
+   * in other words, assume that the first siblings in the child list are subject to being
+   * overpainted by later siblings if their bounds intersect.
+   *
+   * The order of layers, from bottom to top, is:
+   * \li LAYER_BACKGROUND
+   * \li LAYER_WINDOW
+   * \li LAYER_MDI
+   * \li LAYER_CANVAS
+   * \li LAYER_WIDGET
+   * \li LAYER_POPUP
+   * \li LAYER_OVERLAY
+   */
   enum ComponentLayer {
-    LAYER_INVALID,
-    LAYER_BACKGROUND,
-    LAYER_CANVAS,
-    LAYER_WIDGET,
-    LAYER_MDI,
-    LAYER_POPUP,
-    LAYER_OVERLAY,
-    LAYER_WINDOW,
-    LAYER_LAST_DEFINED
+    LAYER_INVALID,/**< Indicates an error condition or uninitialized value. */
+    LAYER_BACKGROUND,/**< The bottom-most layer, over which everything else is painted. 
+		      * The 'desktop background' is generally in this layer. */
+    LAYER_CANVAS,/**< The 'background' layer for most content renderers and UI Component 
+		  * containers. */
+    LAYER_WIDGET,/**< The layer in which the majority of ordinary 'foreground' widgets reside.*/
+    LAYER_MDI,/**< A special layer between LAYER_CANVAS and LAYER_WIDGET, in which the
+	       * 'pseudo windows' (e.g. the MDI frames) reside. 
+	       * @see Component::getMDIZOrder */
+    LAYER_POPUP,/**< A layer for popup window content, above LAYER_WIDGET. */
+    LAYER_OVERLAY,/**< The topmost layer. */
+    LAYER_WINDOW,/**< The layer in which a toplevel window background usually resides. */
+    LAYER_LAST_DEFINED/**< Used only to determine the end of the enumeration. */
   };
 
+  /**
+   * The Component interface is implemented by objects which occupy on-screen space, e.g. objects
+   * which have onscreen visual representations.  The methods in Component allow clients to identify
+   * where the objects lie in the onscreen coordinate system, their relative size, stacking order, and
+   * position.  It also provides a mechanism whereby keyboard focus may be transferred to specific
+   * user interface elements programmatically.  This is a 2D API, coordinates of 3D objects are projected into the
+   * 2-dimensional screen view for purposes of this interface.
+   *
+   * @note the meaning and defined values of the \c short \c coord_type parameter used by some
+   * Component methods is as follows:
+   * \li 0 indicates coord_type_xy_screen, coordinates are relative to the display screen, in pixels.
+   * \li 1 indicates coord_type_xy_window, coordinates are relative to the current toplevel window, in pixels.
+   *
+   * @note Events emitted by Component instances include:
+   * \li \c "object:bounds-changed"
+   * \li \c "object:visible-data-changed"
+   */
   interface Component : Bonobo::Unknown {
-
+      
+        /** 
+	 * @returns \c True if the specified point lies within the Component's bounding box, 
+	 * \c False otherwise. 
+	 */
         boolean contains (in long x, in long y, in short coord_type);
+        /** 
+	 * @returns the Accessible child whose bounding box contains the specified point. 
+	 */
         Accessible getAccessibleAtPoint (in long x, in long y, in short coord_type);
+        /** 
+	 * Obtain the Component's bounding box, in pixels, relative to the specified coordinate system. 
+	 * @returns a BoundingBox which entirely contains the object's onscreen visual representation.
+	 **/
         BoundingBox getExtents (in short coord_type);
+        /** 
+	 * Obtain the position of the current component in the coordinate system specified
+	 * by \c coord_type.
+	 * @param coord_type
+	 * @param x an out parameter which will be back-filled with the returned x coordinate.
+	 * @param y an out parameter which will be back-filled with the returned y coordinate.
+	 */
         void getPosition (out long x, out long y, in short coord_type);
+        /** 
+	 * Obtain the size, in the coordinate system specified by \c coord_type, 
+	 * of the rectangular area which fully contains the object's 
+	 * visual representation, without accounting for viewport clipping. 
+	 * @param width the object's horizontal extents in the specified coordinate system.
+	 * @param height the object's vertical extents in the specified coordinate system.
+	 */
         void getSize (out long width, out long height);
+        /** @returns the ComponentLayer in which this object resides. */
 	ComponentLayer getLayer ();
+        /** 
+	 * Obtain the relative stacking order (i.e. 'Z' order) of an object.
+	 * Larger values indicate that an object is on "top" of the stack, therefore
+	 * objects with smaller MDIZOrder may be obscured by objects with a larger MDIZOrder,
+	 * but not vice-versa. 
+	 * @note only relevant for objects in LAYER_MDI or LAYER_WINDOW 
+	 * @returns an integer indicating the object's place in the stacking order.
+	 */
 	short getMDIZOrder ();
+        /**
+	 * Request that the object obtain keyboard focus.
+	 *  
+	 * @returns \c True if keyboard focus was successfully transferred to the Component. 
+	 */
         boolean grabFocus ();
+        /** 
+	 * Register an EventListener for notification when this object receives keyboard focus.
+	 * @note you probably want to register for ¨focus:¨ events via 
+	 * Registry::registerGlobalEventListener instead. 
+	 */
         void registerFocusHandler (in EventListener handler);
+        /**
+	 * Request that an EventListener registered via registerFocusHandler no longer be notified 
+	 * when this object receives keyboard focus.
+	 */
         void deregisterFocusHandler (in EventListener handler);
 
-	/**
+        /**
+	 * Obtain the alpha value of the component.  An alpha value of 1.0 or greater
+	 * indicates that the object is fully opaque, and an alpha value of 0.0 indicates
+	 * that the object is fully transparent.  Negative alpha values have no defined
+	 * meaning at this time.
+	 *
+	 * @note alpha values are used in conjunction with Z-order calculations to
+	 * determine whether an object wholly or partially obscures another object's 
+	 * visual intersection, in the event that their bounds intersect.
+	 *
+	 * @see STATE_OPAQUE
+	 *
+	 * @since AT-SPI 1.7.0
+	 */
+        double getAlpha ();
+
+	/** \cond
 	 * unImplemented:
 	 *
 	 * placeholders for future expansion.
@@ -57,6 +165,6 @@ module Accessibility {
 	void unImplemented ();
 	void unImplemented2 ();
 	void unImplemented3 ();
-	void unImplemented4 ();
+        /** \endcond */
   };
 };
diff --git a/idl/Accessibility_Desktop.idl b/idl/Accessibility_Desktop.idl
index 9c398f9c..19271227 100644
--- a/idl/Accessibility_Desktop.idl
+++ b/idl/Accessibility_Desktop.idl
@@ -27,12 +27,14 @@
 #include <Accessibility_Accessible.idl>
 
 module Accessibility {
-  interface Desktop : Accessible {
     /**
      * At the moment this is only a marker interface, it acts just like
-     * any other Accessible.
+     * any other Accessible.  In all known implementations, the
+     * children are all instances of Application, but this is not
+     * guaranteed by this interface.
      **/
-	  /**
+    interface Desktop : Accessible {
+	  /** \cond
 	   * unImplemented:
 	   *
 	   * placeholders for future expansion.
@@ -41,6 +43,7 @@ module Accessibility {
 	  void unImplemented2_ ();
 	  void unImplemented3_ ();
 	  void unImplemented4_ ();
+	/** \endcond */
   };
 };
 
diff --git a/idl/Accessibility_EditableText.idl b/idl/Accessibility_EditableText.idl
index 5e39f277..6e878adf 100644
--- a/idl/Accessibility_EditableText.idl
+++ b/idl/Accessibility_EditableText.idl
@@ -24,17 +24,84 @@
 
 module Accessibility {
 
+  /** 
+   * Derived from interface Text, EditableText provides methods for
+   * modifying textual content of components which support editing.
+   * EditableText also interacts with the system clipboard via copyText,
+   * cutText, and pasteText.
+   * 
+   * @note read-only instances of EditableText are possible; 
+   *       These may be instances of a general-purpose component type which are
+   *       sometimes, but not always, user-editable, or may be
+   *       components which are temporarily or circumstantially
+   *       in a non-editable state. 
+   */
   interface EditableText : Text {
-
+    /** 
+     * Replace the text contents with a new string, discarding the old contents.
+     *
+     * @param newContents a UTF-8 string with which the text object's contents will be replaced.
+     * @returns \c True if the text content was successfully changed, \c False otherwise.
+     */
     boolean setTextContents (in string newContents);
+    /** 
+     * Insert new text contents into an existing text object at a given location, while retaining
+     * the old contents.
+     * @param position the character offset into the Text implementor's content at which the
+     *        new content will be inserted.
+     * @param text a UTF-8 string of which \c length characters will be inserted into the text 
+     *         object's text buffer.
+     * @param length the number of characters of \c text to insert.  If the character count
+     *         of \c text is less than or equal to \c length, the entire contents of \c text
+     *         will be inserted.
+     * 
+     * @returns \c True if the text content was successfully inserted, \c False otherwise.
+     */
     boolean insertText (in long position, in string text, in long length);
+    /**
+     * Apply a particular set of attributes to a range of text.
+     *
+     *
+     * @returns \c True if the text attributes were successfully modified, \c False otherwise.
+     */
     boolean setAttributes (in string attributes, in long startPos, in long endPos);
+    /**
+     * Copy a range of text into the system clipboard.
+     * @param startPos the character offset of the first character in the range of text being
+     *        copied.
+     * @param endPos the offset of the first character past the end of the range of text
+     *        being copied.
+     */
     void    copyText (in long startPos, in long endPos);
+    /**
+     * Excise a range of text from a Text object, copying it into the system clipboard.
+     * @param startPos the character offset of the first character in the range of text being
+     *        cut.
+     * @param endPos the offset of the first character past the end of the range of text
+     *        being cut.
+     * @returns \c True if the text was successfully cut, \c False otherwise.
+     */
     boolean cutText (in long startPos, in long endPos);
+    /**
+     * Excise a range of text from a Text object without copying it into the system clipboard.
+     * @param startPos the character offset of the first character in the range of text being
+     *        deleted.
+     * @param endPos the offset of the first character past the end of the range of text
+     *        being deleted.
+     * @returns \c True if the text was successfully deleted, \c False otherwise.
+     */
     boolean deleteText (in long startPos, in long endPos);
+    /**
+     * Copy the text contents of the system clipboard, if any, into a Text object, 
+     * inserting it at a particular character offset.
+     *
+     * @param position the character offset before which the text will be inserted.
+     * @returns \c True if the text was successfully pasted into the Text object, \c False otherwise.
+     */
     boolean pasteText (in long position);
+
     /**
-     * unImplemented7:
+     * unImplemented:
      *
      * placeholders for future expansion. Note that these are named
      * 'unimplemented5 and unimplemented6' to avoid conflict with 
diff --git a/idl/Accessibility_Event.idl b/idl/Accessibility_Event.idl
index 792fa447..d7d11651 100644
--- a/idl/Accessibility_Event.idl
+++ b/idl/Accessibility_Event.idl
@@ -29,20 +29,122 @@ module Accessibility
 {
   interface Accessible;
 
+  /** 
+   * A struct encapsulating detailed information about an Event.
+   * This struct supercedes the previous use of the 'any' field 
+   * in EventDetails; the content previously stored in Event::any_data
+   * is now stored in EventDetails::any_data, and Event::any_data
+   * points to an instance of the EventDetails structure, if
+   * the object's implementation supports event detail reporting,
+   * otherwise Event::any_data contains CORBA_OBJECT_NIL.
+   *
+   * @since AT-SPI 1.7.0
+   */
+  struct EventDetails {
+      Application host_application;
+      Role        source_role;
+      string      source_name;
+      any         any_data;
+  };
+
+  /**
+   * A structure encapsulating information about an event
+   * for which notification was requested.  Usually such notification
+   * is requested via a call to Registry::registerGlobalEventListener.
+   * The structure contains a colon-delimited string indicating the event
+   * type, a reference to the generating Accessible, two detail fields whose
+   * interpretation is event-type-specific, and a final field containing 
+   * event-type-specific data.
+   *
+   * @note Since AT-SPI 1.7.0 the 'any' field contains an EventDetails
+   * struct, which encapsulates additional information about the event
+   * and its generating object.
+   */
   struct Event {
+    /** A colon-delimited string indicating the type of the event.
+     *  The string can be interpreted as 
+     *  \c class:type:subtype
+     *  For instance ¨object:text-changed:insert¨ is an event 
+     *  from the 'Object' class, which corresponds to Accessible objects
+     *  general, the type of the event is a ¨text-changed¨ event (i.e. a change in the
+     *  content of an implementor of the Text interface), and the
+     *  specific subtype of the change is an insertion event.
+     *
+     *  Event classes include the following:
+     *  \li focus:   an object has received keyboard focus.  This event has no type or subtype.
+     *  \li window:  a toplevel window has changed state.
+     *  \li object:  an object (i.e. Accessible) has undergone some change in state, content, 
+     *               or hierarchy
+     *  \li document:a change to a document's content has occurred, or its
+     *               content loading status has changed.
+     *  \li mouse:   an event originating from the pointing device.  Rarely used;
+     *               in most cases clients will wish to register for pointer events via
+     *               the DeviceEventController::registerDeviceEvent method instead.
+     *  \li keyboard: an event indicating that the keyboard state (for example, the
+     *               modifier state) has changed significantly.
+     *               "keyboard:" events are not sent for individual keystrokes except as
+     *               a side-effect of certain keys, for instance modifier keys.
+     *               Clients interested in key events should listen for DeviceEvents
+     *               via DeviceEventController::registerKeystrokeListener instead.
+     *
+     * @note For more information on specific event types, see the documentation for
+     * each of the individual interfaces supported by some Accessible objects.
+     *
+     * @see Accessible, Component, Image, Selection, Table, Text, Value.
+     */ 
     string     type;
+    /** 
+     * The Accessible object which is the source of the event.  The source object is the object
+     * to which the change inferred by the event emission occurs; for instance,
+     * the object emitting a ¨object:parent-changed¨ event is the child, not the parent.
+     * Likewise, the event source of an ¨object:children-changed:insert¨ event is the parent,
+     * not the inserted child.
+     */
     Accessible source;
+    /** An integer whose meaning is event type dependent.  It may indicate the offset of
+     * text being inserted, in the case of ¨object:text-changed:insert¨, or the index of a
+     * newly added child in the case of ¨object:children-changed:add¨.  
+     * @note since most AT-SPI clients react to events via an asynchronous queue, for 
+     * performance reasons, this field may be of limited utility unless the client maintains
+     * a large client-side cache of the hierarchy and contained data.  This is because by the time
+     * such an event is asynchronously processed, the state of the originating object may have 
+     * changed.  In other words, the data in the detail1 member is not state-coherent outside
+     * of the event handler.  More useful results are gotten by examination of the 'any_data' field.
+     */
     long       detail1;
+    /** see description of detail2 */
     long       detail2;
+    /** 
+     * A generic storage location for event-type-specific data which provides more specific
+     * information about the event; for instance, in AT-SPI versions prior to 1.7.0,
+     * in the case of ¨object:text-changed:insert¨ events, this field contains a string 
+     * indicating the inserted text.
+     * 
+     * @note Since AT-SPI 1.7.0, the data contained in this field is an EventDetails struct.
+     */
     any        any_data;
   };
 
+  /** 
+   * A generic interface implemented by objects for the 
+   * receipt of event notifications.  EventListener is the interface from which 
+   * Accessibility::Registry is derived, and via which clients of the Registry
+   * receive notification of changes to an application's user interface and content.
+   */
   interface EventListener : Bonobo::Unknown {
+    /** 
+     * Synchronously notify an EventListener that an event has occurred, by passing it an 
+     * Event struct. 
+     * @param e The Event about which the listener is being notified.
+     */
     void notifyEvent (in Event e);
+
+/** \cond */
     void unImplemented_ ();
     void unImplemented2_ ();
     void unImplemented3_ ();
     void unImplemented4_ ();
+/** \endcond */
   };
 };
 
diff --git a/idl/Accessibility_Hyperlink.idl b/idl/Accessibility_Hyperlink.idl
index 3c45f5da..90eb3bdb 100644
--- a/idl/Accessibility_Hyperlink.idl
+++ b/idl/Accessibility_Hyperlink.idl
@@ -24,14 +24,85 @@
 
 module Accessibility {
 
+  /**
+   * Instances of Hyperlink are returned by Hypertext objects, and are
+   * the means by which end users and clients interact with linked, and in
+   * some cases embedded, content.  Hyperlinks may have multiple "anchors",
+   * where an anchor corresponds to a reference to a particular resource with
+   * a corresponding resource identified (URI).  Hyperlinks may be 
+   * queried for their URIs, or queried for the objects corresponding to their
+   * anchors.  The objects thus obtained are instances of Accessible,
+   * and may be queried, and manipulated via the Action interface. 
+   *
+   * @note A Hyperlink implementor is normally NOT an Accessible; 
+   * the preferred usage is for a Hyperlink's associated "objects"
+   * (accessed via the ::getObject method) are Accessibles.  This means
+   * that Actions such as "open link" are normally invoked on
+   * the result of Hyperlink::getObject rather than directly on the 
+   * Hyperlink instance. For historical reasons some implementors of Hyperlink
+   * implement Action as well.  This usage on the part of implementing
+   * applications and toolkits is discouraged, but clients of Hyperlink
+   * should be aware of it and prepared to handle such usage.
+   */
   interface Hyperlink : Bonobo::Unknown {
+    /** the number of separate anchors associated with this Hyperlink */
     readonly attribute short nAnchors;
+    /** 
+     * the starting offset within the containing Hypertext content 
+     * with which this Hyperlink is associated 
+     */
     readonly attribute long startIndex;
+    /** 
+     * the ending offset within the containing Hypertext content 
+     * with which this Hyperlink is associated; that is, the offset of the
+     * first element past the range within the Hypertext associated with
+     * this Hyperlink. 
+     */
     readonly attribute long endIndex;
+    /** 
+     * Gets the i'th object, (where i is an integer between 0 and
+     * Hyperlink::numAnchors - 1, inclusive) associated with a Hyperlink.
+     * The objects returned are usually actionable (i.e. they should implement
+     * Accessibility::Action), and the available actions often include
+     * "open", "bookmark", "save link as", etc.  They may also implement
+     * Accessibility::StreamableContent, although clients can normally use 
+     * ::getURI to obtain a resource locator via which the object's
+     * data may be accessed.
+     * 
+     * @note the most common application for 'multi anchor'
+     * hyperlinks in HTML is probably "client side imagemaps".
+     * A clickable image which uses the HTML 'usemap' attribute
+     * should have one anchor for every &lt;area&gt; element that
+     * includes an HREF.  The objects corresponding to these map
+     * areas may implement Accessibility::Component, to represent
+     * their onscreen bounding box, and may expose their 'shape' as
+     * as name-value pair via Accessibility::Accessible::getAttributeSet.
+     *
+     * @returns an Accessible object instance representing the
+     * Hyperlink's ith anchor, or through which the content associated with
+     * the \c ith anchor can be
+     * accessed.
+     */
     Accessible getObject (in long i);
+    /** 
+     * Obtain a resource locator ('URI') which can be used to 
+     * access the content to which this link "points" or is connected.
+     * @returns a string corresponding to the URI of the Hyperlink's
+     * 'ith' anchor, if one exists, or a NIL string otherwise.
+     */
     string getURI (in long i);
+    /** 
+     * Check the hyperlink to see if a connection to its backing
+     * content can be established, or if its URI is valid.
+     * @note instances of invalid hyperlinks include links with malformed
+     *       URIs, or for which a contact to the service provider
+     *       specified in the URI cannot be established.
+     * @returns \c True if the object's content is available, or
+     *          \c False if the hyperlink's URI is invalid, or 
+     *          a connection to the resource can not be established.
+     */
     boolean isValid ();
-    /**
+    /** \cond
      * unImplemented:
      *
      * placeholders for future expansion.
@@ -40,5 +111,6 @@ module Accessibility {
     void unImplemented2 ();
     void unImplemented3 ();
     void unImplemented4 ();
+    /** \endcond */
   };
 };
diff --git a/idl/Accessibility_Hypertext.idl b/idl/Accessibility_Hypertext.idl
index 97dc74fd..552483d8 100644
--- a/idl/Accessibility_Hypertext.idl
+++ b/idl/Accessibility_Hypertext.idl
@@ -23,14 +23,52 @@
 #include <Accessibility.idl>
 
 module Accessibility {
-
+  /** 
+   * An interface used for objects which implement linking between
+   * multiple resource or content locations, or multiple 'markers'
+   * within a single document.  A Hypertext instance is associated with
+   * one or more Hyperlinks, which are associated with particular
+   * offsets within the Hypertext's included content.
+   *
+   * @note While this interface is derived from ::Text, 
+   *       there is no requirement that Hypertext instances have
+   *       textual content; they may implement ::Image as well,
+   *       and Hyperlinks need not have non-zero text offsets.
+   */
   interface Hypertext : Bonobo::Unknown {
+    /** 
+     * Query the hypertext object for the number of Hyperlinks it
+     * contains.
+     *
+     * @returns the number of Hyperlinks associated with this Hypertext
+     *  object, as a long integer.
+     */
     long getNLinks ();
+    /** 
+     * Get one of the Hyperlinks associated with this Hypertext object,
+     * by index.
+     *
+     * @param linkIndex an integer from 0 to getNLinks() - 1.
+     * @returns the Hyperlink in this Hypertext object.
+     */
     Hyperlink getLink (in long linkIndex);
+    /** 
+     * Get the hyperlink index, if any, associated with a 
+     * particular character offset in the Hypertext object.
+     * For Hypertext implementors without textual content, all
+     * hyperlinks are associated with character offset '0'.
+     *
+     * @return the index of the Hyperlink associated with character
+     *     offset \c characterIndex, or -1 if no Hyperlink is associated
+     *     with that character offset.
+     */
     long getLinkIndex (in long characterIndex);
+
+    /** \cond */
     void unImplemented ();
     void unImplemented2 ();
     void unImplemented3 ();
     void unImplemented4 ();
+    /** \endcond */
   };
 };
diff --git a/idl/Accessibility_Image.idl b/idl/Accessibility_Image.idl
index 54df08d2..6cf50f8e 100644
--- a/idl/Accessibility_Image.idl
+++ b/idl/Accessibility_Image.idl
@@ -2,7 +2,7 @@
  * AT-SPI - Assistive Technology Service Provider Interface 
  * (Gnome Accessibility Project; http://developer.gnome.org/projects/gap)
  *
- * Copyright 2001 Sun Microsystems, Inc.
+ * Copyright 2001 - 2005 Sun Microsystems, Inc.
  *
  * This library is free software; you can redistribute it and/or
  * modify it under the terms of the GNU Library General Public
@@ -20,14 +20,84 @@
  * Boston, MA 02111-1307, USA.
  */
 
+#include "Accessibility_Accessible.idl"
+
 module Accessibility {
 
+  /** 
+   * An interface implemented by objects which render image data or 
+   * pictorial information to the screen.  When onscreen components include
+   * graphical information that is not purely intended to enhance "3d effect"
+   * or visual layout, but which conveys some semantic or informational 
+   * content to the sighted user, they should implement Image, and that 
+   * semantic content should be conveyed textually to the extent possible 
+   * via the image description, as well as the Accessible::name and 
+   * Accessible::description properties.  
+   */
   interface Image : Bonobo::Unknown  {
+    /**
+     * A UTF-8 string providing a textual description
+     * of what is visually depicted in the image.
+     *
+     * @note It is recommended that imageDescription be the shorter
+     * of the available image descriptions, for instance "alt text"
+     * in HTML images, and a longer description be provided in
+     * Accessible::accessible-description, if available.
+     * A short, one or two word label for the image should be provided in
+     * Accessible::accessible-name.
+     */
     readonly attribute string imageDescription;
+    /** 
+     * A string corresponding to the POSIX LC_MESSAGES locale used 
+     * by the imageDescription.
+     * @since AT-SPI 1.7.0
+     */
+    readonly attribute string imageLocale;
+    /**
+     * Obtain a bounding box which entirely contains the image contents,
+     * as displayed on screen.  The bounds returned do not account for
+     * any viewport clipping or the fact that the image may be
+     * partially or wholly obscured by other onscreen content.
+     * @note This method returns the bounds of the current onscreen
+     * view, and not the nominal size of the source data in the
+     * event that the original image has been rescaled.
+     *
+     * @param coordType If 0, the returned bounding box position is returned
+     * relative to the screen; if 1, the bounding box position is returned 
+     * relative to the containing window.
+     * @returns a BoundingBox enclosing the image's onscreen representation.
+     */
     BoundingBox getImageExtents (in short coordType);
+    /**
+     * Get the coordinates of the current image position on screen.
+     *
+     * @param x Back-filled with the x coordinate of the 
+     * onscreen image (i.e. the minimum x coordinate)
+     * @param y Back-filled with the y coordinate of the 
+     * onscreen image (i.e. the minimum y coordinate)
+     * @param coordType If 0, the returned x and y coordinates are 
+     * returned relative to the screen; 
+     * if 1, they are returned relative to the containing window.
+     */
     void getImagePosition (out long x, out long y, in short coordType);
+    /**
+     * Obtain the width and height of the current onscreen view of the
+     * image.  The extents returned do not account for
+     * any viewport clipping or the fact that the image may be
+     * partially or wholly obscured by other onscreen content.
+     * @note This method returns the size of the current onscreen
+     * view, and not the nominal or "original" size of the source 
+     * image, in the event that the original image has been rescaled.
+     *
+     * @param width Back-filled with the x extents of the 
+     * onscreen image (i.e. the image width in pixels)
+     * @param height Back-filled with the y extents of the 
+     * onscreen image (i.e. the image height in pixels)
+     */
     void getImageSize (out long width, out long height);
+
     /**
+     * \cond
      * unImplemented:
      *
      * placeholders for future expansion.
@@ -35,6 +105,6 @@ module Accessibility {
     void unImplemented ();
     void unImplemented2 ();
     void unImplemented3 ();
-    void unImplemented4 ();
+    /** \endcond */
   };
 };
diff --git a/idl/Accessibility_LoginHelper.idl b/idl/Accessibility_LoginHelper.idl
index 141fb3a2..140aea2b 100644
--- a/idl/Accessibility_LoginHelper.idl
+++ b/idl/Accessibility_LoginHelper.idl
@@ -28,7 +28,10 @@
 module Accessibility {
 
     /**
-     * LoginHelper:
+     * @brief An interface for use by assistive technologies by which
+     * they can access system information and services on a 'need to know'
+     * basis while the screen is locked, during user authentication, or
+     * during other sensitive operations.
      *
      * This interface is intended for use by assistive technologies
      * and related user-enabling services, and by applications and
@@ -38,23 +41,23 @@ module Accessibility {
      * service.
      *
      * Such 'applications' (for instance, screen lock dialogs and
-     * security-enabled web browsers) use the @LoginHelper client
+     * security-enabled web browsers) use the ::LoginHelper client
      * interfaces, and the bonobo-activation query service, to
-     * query for assistive technologies which advertise the @LoginHelper
+     * query for assistive technologies which advertise the ::LoginHelper
      * service.  The client then queries these assistive technologies 
-     * for their device I/O requirements, via the @getDeviceReqs call.
-     * The client may then issue the advisory request @setSafe (TRUE), 
-     * which requests that the @LoginHelper-implementing service make a
+     * for their device I/O requirements, via the ::getDeviceReqs call.
+     * The client may then issue the advisory request ::setSafe (TRUE), 
+     * which requests that the ::LoginHelper -implementing service make a
      * best-effort attempt to make itself more secure (for instance, 
      * an onscreen keyboard might turn off word prediction, and a
      * screenreader may turn off keyboard echo via speech).  The return
-     * value of @setSafe is an advisory indication of whether this attempt
+     * value of ::setSafe is an advisory indication of whether this attempt
      * was successful (no specific guarantees are implied).
      * Once the 'security sensitive' state is exited, the client should 
-     * call @setSafe (FALSE).
+     * call ::setSafe (FALSE).
      * 
-     * The return values from @getDeviceReqs inform the client of which
-     * services the @LoginHelper service (e. g. assistive technology) needs
+     * The return values from ::getDeviceReqs inform the client of which
+     * services the ::LoginHelper service (e. g. assistive technology) needs
      * in order to do its job.  The client may use this information to
      * loosen any restrictions on access which it may currently have in 
      * place (for instance, keyboard grabs, etc.).  If it does not do so,
@@ -64,12 +67,11 @@ module Accessibility {
      **/
   interface LoginHelper : Bonobo::Unknown {
 
-      /* 
-       * WindowInfo:
+      /** 
        * A structure containing info about toplevel X windows that
-       * the @LoginHelper instance wishes to have raised.
+       * the ::LoginHelper instance wishes to have raised.
        *
-       * @winID: The windowing-system-dependeny Window ID of the toplevel window.
+       * @param winID: The windowing-system-dependeny Window ID of the toplevel window.
        */
       struct WindowInfo {
 	  /* string display; */
@@ -82,7 +84,7 @@ module Accessibility {
       /*
        * DeviceReq:
        *
-       * The system and device access and services which the @LoginHelper-implementing 
+       * The system and device access and services which the LoginHelper-implementing 
        * assistive technology requires in order to enable the user to use the system.
        *
        */
@@ -104,30 +106,33 @@ module Accessibility {
 
   	/**
          * setSafe:
+	 * @param safe_mode: \c TRUE if the client is requesting that 'safe mode' be 
+	 *         initiated, \c FALSE if the client is advising that 'safe mode' may be
+	 *         exited, i.e. normal operation may be resumed.
          * 
          * Request a LoginHelper to enter "safe" mode, or
 	 *         inform LoginHelper that "safe" mode may be exited.
-	 *         If @safe_mode is %TRUE, but the return value is %FALSE,
+	 *         If \a safe_mode is \c TRUE, but the return value is \c FALSE,
 	 *         the requesting client may wish to deny services to the 
-	 *         %LoginHelper, for instance avoid raising its toplevels.
+	 *         ::LoginHelper, for instance avoid raising its toplevels.
 	 *         The return value is purely advisory, and no guarantees are 
 	 *         intended about what the implementing LoginHelper will do 
 	 *         to improve security when in "safe" mode.
 	 *
-         * Returns: whether the %LoginHelper is now "safe" or not.
+         * @returns: whether the ::LoginHelper is now "safe" or not.
 	 **/
         boolean setSafe (in boolean safe_mode);
 
   	/**
          * getDeviceReqs:
          * 
-         * Query a @LoginHelper for the types of
+         * Query a ::LoginHelper for the types of
 	 *    device I/O it requires, in order to do its job.
-	 *    For instance, a @LoginHelper which needs to receive keyboard
+	 *    For instance, a ::LoginHelper which needs to receive keyboard
 	 *    events will include 
 	 *    Accessibility_LoginHelper_CORE_KEYBOARD in this list.
 	 *
-         * Returns: A sequence of @LoginHelper_DeviceReq indicating
+         * @returns: A sequence of ::LoginHelper_DeviceReq indicating
 	 *    the device I/O required in order to facilitate end-user access 
 	 *    to the system.
 	 **/
@@ -138,14 +143,15 @@ module Accessibility {
          *
          * Get a list of window IDs that need raising on login. 
          *
-	 * Returns: a sequence containing window IDS for toplevels which
+	 * @returns: a sequence containing window IDS for toplevels which
 	 *          need to be raised/made visible during user authentication, in
-	 *          order for the @LoginHelper to facilitate end-user access to the 
+	 *          order for the ::LoginHelper to facilitate end-user access to the 
 	 *          system.
 	 **/
         WindowList getRaiseWindows ();
 
 	/**
+	 * \cond
 	 * unImplemented:
 	 *
 	 * placeholders for future expansion.
@@ -154,6 +160,7 @@ module Accessibility {
 	void unImplemented2 ();
 	void unImplemented3 ();
 	void unImplemented4 ();
+      /** \endcond */
     };
 
 };
diff --git a/idl/Accessibility_Registry.idl b/idl/Accessibility_Registry.idl
index 88f8bfe0..5a41c32f 100644
--- a/idl/Accessibility_Registry.idl
+++ b/idl/Accessibility_Registry.idl
@@ -34,63 +34,90 @@ module Accessibility {
 
   interface DeviceEventController;
 
+    /** 
+     * The Registry is a service through which applications providing 
+     * accessibility services (servers) can rendezvous with consumers of those
+     * services (Assistive Technologies).  The Registry is the first "port of call" for 
+     * accessible applications and for assistive technologies wishing to query and
+     * interact with those applications.
+     *
+     * The Registry service provides four basic functions to Assistive Technology (AT) clients:
+     * \li it provides a list of the applications who have registered with the AT-SPI
+     * framework, thereby announcing their participation in the AT-SPI framework;
+     * \li it allows AT clients to register for notification of changes in application
+     * state (at-spi Events);
+     * \li it dispatches/relays said events from participating applications to
+     * the registered listeners;
+     * \li it gives access to system device events via the associated DeviceEventController
+     * interface.
+     *
+     * From the point of view of accessible applications (i.e. AT-SPI service producers), 
+     * the Registry is primarily a registration and event delivery service.  Applications 
+     * normally only call the registerApplication and deregisterApplication Registry methods,
+     * and its inherited EventListener::notifyEvent method.
+     *
+     * @note Although all application events are dispatched via the Registry, other AT client 
+     * calls are serviced directly by the applications, rather than being relayed via the
+     * Registry.  The AT client obtains references to these application objects
+     * via the enumeration of Desktop instances whose children are Application instances
+     * (Registry::getDesktopList) and via examination of the 'source' member of the Event 
+     * structure. 
+     *
+     * The Registry normally lives in its own process space; communication via Registry and
+     * both application services and AT clients takes place via IPC.  A process space diagram
+     * illustrating the relationship between applications, Registry, and AT is shown below.
+     * @image html "http://developer.gnome.org/projects/gap/tech-docs/SPIBlockDiagram.png"
+     * 
+     *
+     * @see Desktop, Application, Event, EventListener
+     **/
   interface Registry : EventListener {
 
   	/**
-         * registerApplication:
-         * @application: a reference to the requesting @Application
-         *
          * Register a new application with the accessibility broker.
-         *
+         * @param application: a reference to the requesting Application
 	 **/
         oneway void registerApplication (in Application application);
 
   	/**
+         * De-register an application previously registered with the broker.
          * deregisterApplication:
-         * @application: a reference to the @Application 
+         * @param application: a reference to the Application 
          * to be deregistered.
-	 *
-         * De-register an application previously registered with the broker.
-         *
 	 **/
         void deregisterApplication (in Application application);
 
   	/**
-         * registerGlobalEventListener:
-         * @listener: a reference to the requesting @EventListener.
-         * @eventName: a string which indicates the type of events about 
-         * which the client desires notification.
-         *
          * Register a client's interest in (all) application events of 
          * a certain type.
-         *
+         * @param listener: a reference to the requesting ::EventListener.
+         * @param eventName: a string which indicates the type of events about 
+         * which the client desires notification.
 	 **/
         void registerGlobalEventListener (in EventListener listener,
 					  in string eventName);
 
   	/**
-         * deregisterGlobalEventListener:
-         * @listener: the requesting @EventListener
-         * @eventName: a string indicating the type of events
+         * deregisterGlobalEventListenerAll:
+         * @param listener: the requesting EventListener
          *
          * Request that a previously registered client stop receiving
-         * global notifications for events of a certain type.
+         * global notifications for all events for which it was registered.
          *
 	 **/
-
         void deregisterGlobalEventListenerAll (in EventListener listener);
+
   	/**
          * deregisterGlobalEventListener:
-         * @listener: the requesting @EventListener
-         * @eventName: a string indicating the type of events
+         * @param listener: the requesting EventListener
+         * @param eventName: a string indicating the type of events
          *
          * Request that a previously registered client stop receiving
          * global notifications for events of a certain type.
          *
 	 **/
-
         void deregisterGlobalEventListener (in EventListener listener, 
-					    in string event_name);
+					    in string eventName);
         /** 
          * event types: "Window" "Desktop"
          *              "Window:Create" "Window:Destroy"
@@ -112,39 +139,37 @@ module Accessibility {
          * getDesktopCount:
          *
          * Get the current number of desktops.
-	 * Returns: a short integer indicating the current number of 
-         * @Desktops.
+	 * @returns a short integer indicating the current number of 
+         * Desktops.
 	 **/
         short getDesktopCount ();
 
   	/**
          * getDesktop:
-         * @n: the index of the requested @Desktop.
+         * @n: the index of the requested Desktop.
          *
          * Get the nth accessible desktop. 
          *
-	 * Returns: a reference to the requested @Desktop.
+	 * @returns a reference to the requested Desktop.
 	 **/
         Desktop getDesktop (in short n);
 
   	/**
-         * getDesktopList:
-         *
          * Get a list of accessible desktops. 
          *
-	 * Returns: a sequence containing references to
-         * the @Desktops.
+	 * @returns: a sequence containing references to
+         * the Desktops.
 	 **/
         DesktopSeq getDesktopList ();
 
   	/**
-         * getDeviceEventController:
+         * Obtain an object which can be used to request device event notifications.
          *
-	 * Returns: an object implementing DeviceEventController
+	 * @returns: an object implementing DeviceEventController
 	 **/
         DeviceEventController getDeviceEventController ();
 
-	/**
+	/** \cond
 	 * unImplemented:
 	 *
 	 * placeholders for future expansion.
@@ -155,58 +180,191 @@ module Accessibility {
 	void unImplemented4 ();
 	void unImplemented5 ();
 	void unImplemented6 ();
+      /** \endcond */
     };
 
-  /* Deprecated, DO NOT USE! */
+    /** Deprecated, DO NOT USE! */
   enum KeyEventType {
     KEY_PRESSED,
     KEY_RELEASED
   };
 
+  /** Used to specify the event types of interest to an EventListener, or
+   * to identify the type of an event for which notification has been sent. 
+   * @see EventTypeSeq, DeviceEvent::type
+   */
   enum EventType {
-    KEY_PRESSED_EVENT,
-    KEY_RELEASED_EVENT,
-    BUTTON_PRESSED_EVENT,
-    BUTTON_RELEASED_EVENT
+      KEY_PRESSED_EVENT, /**< key on a keyboard device was pressed. */
+      KEY_RELEASED_EVENT, /**< key on a keyboard device was released. */
+      BUTTON_PRESSED_EVENT,/**< button on a non-keyboard human interface device 
+			    * (HID) was pressed */
+      BUTTON_RELEASED_EVENT /**< button on a non-keyboard human interface device 
+			     * (HID) was pressed */
   };
 
+    /** Used when synthesizing keyboard input via DeviceEventController:generateKeyboardEvent.*/
   enum KeySynthType {
-    KEY_PRESS,
-    KEY_RELEASE,
-    KEY_PRESSRELEASE,
-    KEY_SYM,
-    KEY_STRING
+    KEY_PRESS,/** emulate the pressing of a hardware keyboard key. */
+    KEY_RELEASE,/** emulate the release of a hardware keyboard key. */
+    KEY_PRESSRELEASE,/** a hardware keyboard key is pressed and immediately released. */
+    KEY_SYM,/** a symbolic key event is generated, without specifying a hardware key. 
+	     * @note if the keysym is not present in the current keyboard map,
+	     * the DeviceEventController instance has a limited ability to generate
+	     * such keysyms on-the-fly.  Reliability of generateKeyboardEvent calls
+	     * using out-of-keymap keysyms will vary from system to system, and on the
+	     * number of different out-of-keymap being generated in quick succession.
+	     * In practice this is rarely significant, since the keysyms of interest to
+	     * AT clients and keyboard emulators are usually part of the current keymap, i.e.
+	     * present on the system keyboard for the current locale (even if a physical
+	     * hardware keyboard is not connected.
+	     */
+    KEY_STRING /** a string is converted to its equivalent keyboard events and emitted. 
+		* If the string consists of complex character or composed characters
+		* which are not in the current keymap, string emission is subject to the
+		* out-of-keymap limitations described for KeySynthType::KEY_SYM.
+		* In practice this limitation primarily effects Chinese and Japanese locales.
+		*/
   };
 
   enum ModifierType {
-    MODIFIER_SHIFT,
-    MODIFIER_SHIFTLOCK,
-    MODIFIER_CONTROL,
-    MODIFIER_ALT,
-    MODIFIER_META,
+    MODIFIER_SHIFT, /** The left or right 'Shift' key */
+    MODIFIER_SHIFTLOCK, /** The ShiftLock or CapsLock key */
+    MODIFIER_CONTROL,/** 'Control'/'Ctrl' */
+    MODIFIER_ALT,/** The Alt key (as opposed to AltGr) */
+    MODIFIER_META,/** depending on the platform this may map to 'Window', 'Function', 'Meta',
+		   * 'Menu', or 'NumLock'.  
+		   *  Such 'Meta keys' will map to one of META, META2, META3.
+		   * On X Windows platforms these META values map to 
+		   * the modifier masks Mod1Mask, Mod2Mask, Mod3Mask, e.g. an event having
+		   * ModifierType::MODIFIER_META2 means that the 'Mod2Mask' bit is
+		   * set in the corresponding XEvent.
+		   */
     MODIFIER_META2,
     MODIFIER_META3,
-    MODIFIER_NUMLOCK
+    MODIFIER_NUMLOCK/** A symbolic meta key name that is mapped by AT-SPI to the 
+		     *  appropriate META value, for the convenience of the client.
+		     */
   };
 
+  /** A structure that encapsulates the characteristics of the event notifications
+   * that should be sent to an EventListener in response to a call to
+   * DeviceEventController::registerKeystrokeListener or 
+   * DeviceEventController::registerDeviceEventListener. */
   struct EventListenerMode {
-    boolean synchronous;
-    boolean preemptive;
-    boolean global;	  
+    boolean synchronous; /**< If \c True, specifies that
+			  * DeviceEventController should block while waiting 
+			  * for client to process the requested event notifications; 
+			  * ordinarily should be used only when client needs to perform
+			  * operations synchronously with event delivery. Note that because
+			  * of the architecture of device event systems in general,
+			  * use of this flag may not block delivery of the event to 
+			  * the currently focussed application unless it is used in 
+			  * conjunction with the preemptive flag. */
+    boolean preemptive; /**< If \c True, specifies that 
+			 * Listener is allowed to pre-empt the delivery of the event,
+			 * effectively "consuming" it such that it is not delivered 
+			 * to the currently focussed desktop application. 
+			 * Key events consumed via this API will not be 
+			 * available for use by other applications or services, so this
+			 * option should be used sparingly. */
+    boolean global; /**< If \c True, specifies that
+		     * Event notifications should be sent regardless of whether the
+		     * currently focussed application participates in the AT-SPI 
+		     * infrastructure.  On systems with the XEvIE X extension, this flag
+		     * also allows access to events which are already subject to 
+		     * interception via a "system keygrab" (as described in the X Window System
+		     * documentation for XGrabKey).  The 'global' and 'preemptive' flags
+		     * should only be used together for the purposes of registering
+		     * "system global key shortcuts" i.e. command keys for use by the
+		     * assistive technology. */
   };
 
+  /** 
+   * an unsigned short int consisting of zero or more of the following
+   * values OR'ed together:
+   *
+   * \li \c 1<<::KEY_PRESSED_EVENT  = 1
+   * \li \c 1<<::KEY_RELEASED_EVENT = 2
+   * \li \c 1<<::BUTTON_PRESSED_EVENT = 3,
+   * \li \c 1<<::BUTTON_RELEASED_EVENT = 4
+   **/
   typedef unsigned long ControllerEventMask;
 
+  /** A structure which encapsulates information about a device event. */
   struct DeviceEvent {
-    EventType type; 
-    long  id;
-    short hw_code;
-    unsigned short modifiers;
-    unsigned long timestamp;
-    string event_string;
-    boolean is_text;
+    EventType type; /**< Identifies the type of the containing DeviceEvent. */
+    long  id; /**< an identifier which identifies this event in the event stream. 
+	       * On X Window systems this corresponds to the XEvent serial number.
+	       */
+    short hw_code; /**< a numeric code which is hardware and system-dependent, identifying the
+		    * specific hardware button or key on the device for which the event has
+		    * occurred. On X Window systems, for global key notifications and for most
+		    * non-global key notifications as well, this code corresponds to the
+		    * XKeycode.  For switch and button events it indicates the switch
+		    * or button number.
+		    * @note
+		    * For technical reasons, this code may differ from the XKeycode
+		    * when generated by Java applications for consumption by non-global
+		    * key listeners.  This is subject to change in future versions of the
+		    * DeviceEventController implementation.
+		    */
+
+    unsigned short modifiers; /**< an unsigned short int consisting of zero or more of the following
+			       * values OR'ed together:
+			       * \li \c 1<<::MODIFIER_SHIFT   (=1, corresponds to Xlib's ShiftMask)
+			       * \li \c 1<<::MODIFIER_SHIFTLOCK    (=2, corresponds to Xlib's LockMask)
+			       * \li \c 1<<::MODIFIER_CONTROL (=4, corresponds to Xlib's ControlMask)
+			       * \li \c 1<<::MODIFIER_ALT    (=8, corresponds to Xlib's Mod1Mask)
+			       * \li \c 1<<::MODIFIER_META    (=16, corresponds to Xlib's Mod2Mask)
+			       * \li \c 1<<::MODIFIER_META2    (=32, corresponds to Xlib's Mod3Mask)
+			       * \li \c 1<<::MODIFIER_META3    (=64, corresponds to Xlib's Mod4Mask)
+			       **/
+    unsigned long timestamp; /**< an unsigned integer representing the time that the 
+			      * event occurred.  On X Window systems this event is 
+			      * a time in milliseconds from some arbitrary starting
+			      * point; it therefore has a cycle time of approximately
+			      * 50 days.
+			      */
+    string event_string; /**< A string representation of the event.  If is_text is
+			  * \c True, then this string represents the character or typographic
+			  * sequence that would be received by a focussed text input field.
+			  * event_string is in general suitable for exposure to the
+			  * end-user for purposes of keyboard echo.
+			  */
+    boolean is_text; /**< \c True if the event results in the insertion of characters 
+		      * into an input text buffer, or would do so if delivered to a focussed
+		      * text input field. ¨Typographical¨ key events have this field set to
+		      * \c True, whereas ¨control¨ key events generally do not.
+		      */
   };
 
+  /** 
+   * A structure which defines the identity of a key for which notifications
+   * are to be requested.  The data in the members of a ::KeyDefinition are used to
+   * determine which keyboard events 'match' the notification request filed by a client.
+   *
+   * @note Ordinarily a KeyDefinition specifies one and only one of the criteria below; 
+   * the result of using a KeyDefinition with multiple members defined as nonzero is
+   * undefined.
+   *
+   * @param keycode if nonzero, the numeric, system-dependent value corresponding to a 
+   * physical key on the keyboard.  Keycode values have no semantic meaning to the end-user,
+   * and may depend on the user's hardware and operating environment.  They therefore are
+   * rarely useful "as-is" to AT clients, unless the client has used operating system
+   * services to identify the hardward keycode associated with a particular key symbol.
+   * Notifications for key events requested by keycode are less dependent on modifier state
+   * than \c keysym based notifications, but some hardware (notably many laptops) may generate
+   * more than one keycode for the same physical key, depending on the state of physical 
+   * shift/modifier keys.
+   * @param keysym if nonzero, the numeric value corresponding to the X Keysym of the key for which 
+   * notification is requested.  Note that the presence of active modifiers will affect
+   * whether notification for key events requested via "keysym" specification takes place, 
+   * since the keysym depends on the modifier state for most keys.
+   * @param keystring if non-NULL, the string value of the inserted characters if the corresponding
+   * key event has ::KeyEvent:is_text set to \c True, or the string representing the
+   * 'name' of the key.  On X11 systems, the string 'name' of non-printing keysyms corresponds
+   * to the values in "keysymdef.h" as provided by Xlib, with the leading "XK_" stripped off.
+   **/
   struct KeyDefinition {
     long keycode;
     long keysym;
@@ -218,33 +376,56 @@ module Accessibility {
   typedef sequence< EventType > KeyEventTypeSeq;
   typedef sequence< EventType > EventTypeSeq;
 
+  /** This interface should be implemented by AT-SPI clients who wish to 
+   * make use of the DeviceEventController to receive device event notifications.
+   * DeviceEvents include keyboard events and mouse button/motion events.
+   **/
   interface DeviceEventListener : Bonobo::Unknown {
+      /** Notify an interested DeviceEventListener that a DeviceEvent has occurred.
+       * @returns \c True if the recipient/consumer wishes to consume the event, i.e.
+       * prevent it from being delivered to the desktop, \c False if the event should 
+       * continue to be delivered as normal.
+       */
         boolean notifyEvent (in DeviceEvent event);
+      /** \cond */
         void    unImplemented__ ();
         void    unImplemented_2_ ();
         void    unImplemented_3_ ();
         void    unImplemented_4_ ();
         void    unImplemented_5_ ();
         void    unImplemented_6_ ();
+      /** \endcond */
   };
 
+  /** 
+   * The interface via which clients request notification of device events, and
+   * through which device events may be simulated.
+   ***/
   interface DeviceEventController : Bonobo::Unknown {
 
   	/**
-         * registerKeystrokeListener:
-         * @listener: a @DeviceEventListener which will intercept key events.
-         * @keys:     a @KeySet indicating which keys to intercept, or KEYSET_ALL_KEYS.
-         * @mask:     a @ControllerEventMask filtering the intercepted key events.
-	 * @type:     an @EventType mask that may created by ORing event types together.
-	 * @is_synchronous: a @boolean indicating whether the listener should 
-	 *            receive the events synchronously, potentially consuming them,
-	 *            or just be notified asynchronously of those events that have
-	 *            been generated.
-	 * Returns: %true if successful, %false if not
-         *
          * Register to intercept keyboard events, and either pass them on or
          * consume them. 
          *
+         * @param listener: a DeviceEventListener which will intercept key events.
+         * @param keys:     a KeySet indicating which keys to intercept, or KEYSET_ALL_KEYS.
+         * @param mask:     a ControllerEventMask filtering the intercepted key events.
+	 * @param type:     a KeyEventTypeSeq that may created by ORing event types together.
+	 * @param mode: an EventListenerMode indicating whether the listener should 
+	 *            receive the events synchronously, potentially consuming them,
+	 *            or just be notified asynchronously of those events that have
+	 *            been generated.
+	 * @note Some platforms have limited support for global, preemptive EventListenerMode.
+	 * Such a registration may fail if another client already has priority for preemptive
+	 * access to one or more of the members of the KeySet.  AT consumers have the option
+	 * of re-trying the request without the global flag, or without the preemptive flag,
+	 * or of re-trying with a different KeySet.  The best support for pre-emptive
+	 * global keyboard listeners is provided on platforms whose Xserver implementation
+	 * provides the XEvIE extension.
+	 *
+	 * @returns \c True if the DeviceEventListener was successfully registered
+	 * for the requested KeySet, ControllerEventMask, event types, and EventListenerMode; 
+	 * otherwise returns \c False.
 	 **/
         boolean registerKeystrokeListener (in DeviceEventListener listener,
 					in KeySet keys,
@@ -253,16 +434,11 @@ module Accessibility {
 					in EventListenerMode mode);
     
   	/**
-         * deregisterKeystrokeListener:
-         * @listener: a @DeviceEventListener which will intercept key events.
-         * @keys:     a @KeySet indicating which keys to intercept, or KEYSET_ALL_KEYS.
-         * @mask:     a @ControllerEventMask filtering the intercepted key events.
-	 * @type:     an @EventType mask that may created by ORing event types together.
-	 *
-	 * Returns: void
-         *
          * De-register a previously registered keyboard eventlistener.
-         *
+         * @param listener: a DeviceEventListener which will intercept key events.
+         * @param keys:     a KeySet indicating which keys to intercept, or KEYSET_ALL_KEYS.
+         * @param mask:     a ControllerEventMask filtering the intercepted key events.
+	 * @param type:     an EventType mask that may created by ORing event types together.
 	 **/
         void deregisterKeystrokeListener (in DeviceEventListener listener,
 					  in KeySet keys,
@@ -270,78 +446,88 @@ module Accessibility {
 					  in KeyEventTypeSeq type);
     
   	/**
-         * registerDeviceEventListener:
-         * @listener: a @DeviceEventListener which will intercept events.
-	 * @typeseq:  an @EventTypeSeq indicating which event types to listen for.
-	 * Returns: %true if successful, %false if not
-         *
          * Register to intercept events, and either pass them on or
          * consume them. To listen to keyboard events use registerKeystrokeListener
 	 * instead.
-         *
+         * @param listener: a DeviceEventListener which will intercept events.
+	 * @param typeseq:  an EventTypeSeq indicating which event types to listen for.
+	 * @returns \c True if successful, \c False if not
 	 **/
         boolean registerDeviceEventListener (in DeviceEventListener listener,
 					     in EventTypeSeq typeseq);
     
   	/**
-         * deregisterDeviceEventListener:
-         * @listener: a @DeviceEventListener which will intercept events.
-	 * @typeseq:  an @EventTypeSeq indicating which event types to stop
-	 *            listening for.
-	 *
-	 * Returns: void
-         *
          * De-register a previously registered keyboard eventlistener.
-         *
+         * @param listener: a DeviceEventListener which will intercept events.
+	 * @param typeseq:  an EventTypeSeq indicating which event types to stop
+	 *            listening for.
 	 **/
         void deregisterDeviceEventListener (in DeviceEventListener listener,
 					    in EventTypeSeq typeseq);
     
+      /** 
+       * Notify the Registry instance that a device event has taken place, and
+       *       allow pre-emptive listeners the opportunity to 'consume' the event
+       *       and thus prevent its further issuance/forwarding.  This is the 
+       *       method used by accessibility bridges to forward "toolkit dependent"
+       *       device events to the Registry from the application's process space.
+       *
+       * @note AT clients do not normally need to use this method, it is intended for use
+       *       by toolkit bridges and special-purpose applications.
+       *
+       * @returns \c True if the event was consumed by a (pre-emptive) listener,
+       *          \c False if not (in which case the device event will be forwarded
+       *          as normal to any application which would normally receive it, e.g.
+       *          the currently active application in the case of mouse or keyboard events).
+       **/
         boolean notifyListenersSync (in DeviceEvent event);
 
+      /** 
+       * Notify the Registry instance that a device event has taken place in
+       *       an asynchronous manner.  This is the 
+       *       method used by accessibility bridges to forward "toolkit dependent"
+       *       device events to the Registry from the application's process space.
+       *       If the event in question is potentially pre-emptible.
+       *       ::notifyListenersSync should be used instead.
+       *
+       * @note AT clients do not normally need to use this method, it is intended for use
+       *       by toolkit bridges and special-purpose applications.
+       **/
         oneway void notifyListenersAsync (in DeviceEvent event);
 
         /**
-         * generateKeyboardEvent:
-         * @keycode: a long integer indicating the keycode of
+         * Synthesize a keyboard event.
+         * @param keycode: a long integer indicating the keycode of
 	 *          the keypress to be synthesized.
-	 * @keystring: an optional UTF-8 string indicating a complex
+	 * @param keystring: an optional UTF-8 string indicating a complex
 	 *          keyboard input event.
-	 * @type: a #KeySynthType indicating the type of event(s) to be 
+	 * @param type: a KeySynthType indicating the type of event(s) to be 
 	 *          synthesized: a key press, release, press-release pair,
 	 *          or a complex input string (for instance from an
 	 *          internationalized or complex text input method, or
 	 *          a composed character).
 	 *
-	 * Note that @keycode may be truncated before being
+	 * @note keycode may be truncated before being
 	 *          processed, as keycode length may be platform-dependent
 	 *          and keycode ranges are generally much smaller than
 	 *          CORBA_long. 
-	 * One or the other of @keycode or @keystring are generally NULL, 
-	 *          (but not both), depending on the value of @type.
+	 * One or the other of keycode or keystring are generally NULL, 
+	 *          (but not both), depending on the value of \c type.
 	 *
-         * Returns: void
-         *
-         * Synthesize a keyboard event.
-         *
          **/
          void generateKeyboardEvent (in long keycode, 
 				     in string keystring, 
 				     in KeySynthType type);
 
         /**
-         * generateMouseEvent:
-         * @x: a long integer indicating the screen x coord for the mouse event.
-         * @y: a long integer indicating the screen y coord for the mouse event.
-         * @eventName: a string indicating the type of mouse event, e.g. "button1up"
-         * Returns: void
-         *
          * Synthesize a mouse event.
-         *
+         * @param x: a long integer indicating the screen x coord for the mouse event.
+         * @param y: a long integer indicating the screen y coord for the mouse event.
+         * @param eventName: a string indicating the type of mouse event, e.g. "button1up"
          **/
          void generateMouseEvent (in long x, in long y, in string eventName);
 
-	 /**
+	 /** \cond
 	  * unImplemented:
 	  *
 	  * placeholders for future expansion.
@@ -350,6 +536,7 @@ module Accessibility {
 	 void unImplemented2 ();
 	 void unImplemented3 ();
 	 void unImplemented4 ();
+      /** \endcond */
     }; 
 };
 
diff --git a/idl/Accessibility_Relation.idl b/idl/Accessibility_Relation.idl
index 2d2b1e42..b6f2911b 100644
--- a/idl/Accessibility_Relation.idl
+++ b/idl/Accessibility_Relation.idl
@@ -25,39 +25,97 @@
 
 module Accessibility {
 
+    /** 
+     * RelationType specifies a relationship between objects (possibly one-to-many or many-to-one)
+     * outside of the normal parent/child hierarchical relationship.  It allows better semantic
+     * identification of how objects are associated with one another.
+     * For instance the RELATION_LABELLED_BY relationship may be used to identify labelling information
+     * that should accompany the accessibleName property when presenting an object's content or identity
+     * to the end user.  Similarly, RELATION_CONTROLLER_FOR can be used to further specify the context
+     * in which a valuator is useful, and/or the other UI components which are directly effected by
+     * user interactions with the valuator.  Common examples include association of scrollbars with
+     * the viewport or panel which they control.
+     */
   enum RelationType {
+    /** Not a meaningful relationship; clients should not normally encounter this RelationType value. */
     RELATION_NULL,
+    /** Object is a label for one or more other objects. */
     RELATION_LABEL_FOR,
+    /** Object is labelled by one or more other objects. */
     RELATION_LABELLED_BY,
+    /** Object is an interactive object which modifies the state, onscreen location, or other attributes
+     * of one or more target objects. */
     RELATION_CONTROLLER_FOR,
+    /** Object state, position, etc. is modified/controlled by user interaction with one or 
+     * more other objects.   For instance a viewport or scroll pane may be CONTROLLED_BY scrollbars. */
     RELATION_CONTROLLED_BY,
+    /** Object has a grouping relationship (e.g. ¨same group as¨) to one or more other objects.  */
     RELATION_MEMBER_OF,
+    /** Object is a tooltip associated with another object. */
     RELATION_TOOLTIP_FOR,
+    /** Reserved for future use. */
     RELATION_NODE_CHILD_OF,
+    /** Used to indicate that a relationship exists, but its type is not specified in the enumeration
+     * and must be obtained via a call to getRelationTypeName.  */
     RELATION_EXTENDED,
+    /** Object renders content which flows logically to another object.  
+     * For instance, text in a paragraph may flow to another object which is not the 
+     * ¨next sibling¨ in the accessibility hierarchy. */
     RELATION_FLOWS_TO,
+    /** Reciprocal of RELATION_FLOWS_TO. */
     RELATION_FLOWS_FROM,
+    /** Object is visually and semantically considered a subwindow of another object, even though
+     * it is not the object's child.  Useful when dealing with embedded applications and other cases
+     * where the widget hierarchy does not map cleanly to the onscreen presentation.  */
     RELATION_SUBWINDOW_OF,
+    /** Similar to SUBWINDOW_OF, but specifically used for cross-process embedding.  */
     RELATION_EMBEDS,
+    /** Reciprocal of RELATION_EMBEDS; Used to denote content rendered by embedded renderers that
+     * live in a separate process space from the embedding context.  */
     RELATION_EMBEDDED_BY,
+    /** Denotes that the object is a transient window or frame associated with another onscreen object.
+     * Similar to TOOLTIP_FOR, but more general.  Useful for windows which are technically 
+     * toplevels but which, for one or more reasons, do not explicitly cause their associated
+     * window to lose ¨window focus¨.   Creation of a ROLE_WINDOW object with the POPUP_FOR relation
+     * usually requires some presentation action on the part of assistive technology clients, even though
+     * the previous toplevel ROLE_FRAME object may still be the active window.  */
     RELATION_POPUP_FOR,
+    /** This is the reciprocal relation to RELATION_POPUP_FOR. */
+    RELATION_PARENT_WINDOW_OF,
+    /** Do not use as a parameter value, used to determine the size of the enumeration. */
     RELATION_LAST_DEFINED
   };
 
-  /*
-   * This interface inherits from a base class implementing ref counts.
+  /** 
+   * An interface via which objects' non-hierarchical relationships to one another 
+   * are indicated.  An instance of Relations represents a "one-to-many" correspondance.
+   *
+   * @note This interface inherits from a base class implementing ref counts.
    */
-
   interface Relation : Bonobo::Unknown {
+
+    /** @returns the RelationType of this Relation. */
     RelationType        getRelationType ();
-    string getRelationTypeName ();
+
+    /** @returns an unlocalized string representing the relation type. */
+    string              getRelationTypeName ();
+
+    /** @returns the number of objects to which this relationship applies. */
     short               getNTargets ();
+
+    /** @returns an Object which is the 'nth'target of this Relation, e.g. the Object at index i
+     * in the list of Objects having the specified relationship to this Accessible.  
+     * \note This target should always implement Accessible, though it is returned as an Object.
+     * (In this respect this method is probably ill-specified.)
+     **/
     Object		getTarget (in short index);
-    /* placeholders for future expansion */
+
+    /** \cond placeholders for future expansion */
     void unImplemented ();
     void unImplemented2 ();
     void unImplemented3 ();
     void unImplemented4 ();
+    /** \endcond */
   };
 };
 
diff --git a/idl/Accessibility_Role.idl b/idl/Accessibility_Role.idl
index a64f66a2..b70e86ad 100644
--- a/idl/Accessibility_Role.idl
+++ b/idl/Accessibility_Role.idl
@@ -26,255 +26,267 @@
 module Accessibility {
 
   enum Role {
+  /** A Role indicating an error condition, such as uninitialized Role data. */
   ROLE_INVALID,
-  /* Object is a label indicating the keyboard accelerators for the parent  */
+  /** Object is a label indicating the keyboard accelerators for the parent  */
   ROLE_ACCELERATOR_LABEL,
-  /* Object is used to alert the user about something */
+  /** Object is used to alert the user about something */
   ROLE_ALERT,
-  /* Object contains a dynamic or moving image of some kind */
+  /** Object contains a dynamic or moving image of some kind */
   ROLE_ANIMATION,
-  /* Object is a 2d directional indicator */
+  /** Object is a 2d directional indicator */
   ROLE_ARROW,
-  /* Object contains one or more dates, usually arranged into a 2d list */
+  /** Object contains one or more dates, usually arranged into a 2d list */
   ROLE_CALENDAR,
-  /* Object that can be drawn into and is used to trap events */
+  /** Object that can be drawn into and is used to trap events */
   ROLE_CANVAS,
-  /*
+  /**
    * A choice that can be checked or unchecked and provides a separate
    * indicator for the current state.
    */
   ROLE_CHECK_BOX,
-  /* A menu item that behaves like a check box (see ROLE_CHECK_BOX) */
+  /** A menu item that behaves like a check box (see ROLE_CHECK_BOX) */
   ROLE_CHECK_MENU_ITEM,
-  /* A specialized dialog that lets the user choose a color. */
+  /** A specialized dialog that lets the user choose a color. */
   ROLE_COLOR_CHOOSER,
-  /* The header for a column of data */
+  /** The header for a column of data */
   ROLE_COLUMN_HEADER,
-  /* A list of choices the user can select from */
+  /** A list of choices the user can select from */
   ROLE_COMBO_BOX,
-  /* An object which allows entry of a date */
+  /** An object which allows entry of a date */
   ROLE_DATE_EDITOR,
-  /* An inconifed internal frame within a DESKTOP_PANE */
+  /** An inconifed internal frame within a DESKTOP_PANE */
   ROLE_DESKTOP_ICON,
-  /*
+  /**
    * A pane that supports internal frames and iconified versions of those
    * internal frames.
    */
   ROLE_DESKTOP_FRAME,
-  /* 
+  /** 
    * An object that allows a value to be changed via rotating a visual element,
    * or which displays a value via such a rotating element. 
    */
   ROLE_DIAL,
-  /* A top level window with title bar and a border */
+  /** A top level window with title bar and a border */
   ROLE_DIALOG,
-  /*
+  /**
    * A pane that allows the user to navigate through and select the contents
    * of a directory
    */
   ROLE_DIRECTORY_PANE,
-  /*
+  /**
    * A specialized dialog that displays the files in the directory and lets
    * the user select a file, browse a different directory, or specify a
    * filename.
    */
   ROLE_DRAWING_AREA,
-  /*
+  /**
    * An object used for drawing custom user interface elements.
    */
   ROLE_FILE_CHOOSER,
-  /*
+  /**
    * A object that fills up space in a user interface
    */
   ROLE_FILLER,
-  /* XXX Don't know sure about this. */
+  /** XXX Don't use, reserved for future use. */
   ROLE_FOCUS_TRAVERSABLE,
-  /* Allows selection of a display font */
+  /** Allows selection of a display font */
   ROLE_FONT_CHOOSER,
-  /* A top level window with a title bar, border, menubar, etc. */
+  /** A top level window with a title bar, border, menubar, etc. */
   ROLE_FRAME,
-  /* A pane that is guaranteed to be painted on top of all panes beneath it */
+  /** A pane that is guaranteed to be painted on top of all panes beneath it */
   ROLE_GLASS_PANE,
-  /*
+  /**
    * A document container for HTML, whose children
    * represent the document content.
    */
   ROLE_HTML_CONTAINER,
-  /* A small fixed size picture, typically used to decorate components */
+  /** A small fixed size picture, typically used to decorate components */
   ROLE_ICON,
-  /* An image, typically static. */
+  /** An image, typically static. */
   ROLE_IMAGE,
-  /* A frame-like object that is clipped by a desktop pane. */
+  /** A frame-like object that is clipped by a desktop pane. */
   ROLE_INTERNAL_FRAME,
-  /* An object used to present an icon or short string in an interface */
+  /** An object used to present an icon or short string in an interface */
   ROLE_LABEL,
-  /*
+  /**
    * A specialized pane that allows its children to be drawn in layers,
    * providing a form of stacking order.
    */
   ROLE_LAYERED_PANE,
-  /*
+  /**
    * An object that presents a list of objects to the user and allows the
    * user to select one or more of them.
    */
   ROLE_LIST,
-   /* An object that represents an element of a list. */
+  /** An object that represents an element of a list. */
   ROLE_LIST_ITEM,
-  /*
+  /**
    * An object usually found inside a menu bar that contains a list of
    * actions the user can choose from.
    */
   ROLE_MENU,
-  /*
+  /**
    * An object usually drawn at the top of the primary dialog box of an
    * application that contains a list of menus the user can choose from.
    */
   ROLE_MENU_BAR,
-  /*
+  /**
    * An object usually contained in a menu that presents an action the
    * user can choose.
    */
   ROLE_MENU_ITEM,
-  /* A specialized pane whose primary use is inside a DIALOG */
+  /** A specialized pane whose primary use is inside a DIALOG */
   ROLE_OPTION_PANE,
-  /* An object that is a child of a page tab list */
+  /** An object that is a child of a page tab list */
   ROLE_PAGE_TAB,
-  /*
+  /**
    * An object that presents a series of panels (or page tabs), one at a time,
    * through some mechanism provided by the object.
    */
   ROLE_PAGE_TAB_LIST,
-  /* A generic container that is often used to group objects. */
+  /** A generic container that is often used to group objects. */
   ROLE_PANEL,
-  /*
+  /**
    * A text object uses for passwords, or other places where the text
    * content is not shown visibly to the user.
    */
   ROLE_PASSWORD_TEXT,
-  /*
+  /**
    * A temporary window that is usually used to offer the user a list of
    * choices, and then hides when the user selects one of those choices.
    */
   ROLE_POPUP_MENU,
-  /* An object used to indicate how much of a task has been completed. */
+  /** An object used to indicate how much of a task has been completed. */
   ROLE_PROGRESS_BAR,
-  /*
+  /**
    * An object the user can manipulate to tell the application to do
    * something.
    */
   ROLE_PUSH_BUTTON,
-  /*
+  /**
    * A specialized check box that will cause other radio buttons in the
    * same group to become uncghecked when this one is checked.
    */
   ROLE_RADIO_BUTTON,
-  /* Object is both a menu item and a "radio button" (see ROLE_RADIO_BUTTON) */
+  /** Object is both a menu item and a "radio button" (see ROLE_RADIO_BUTTON) */
   ROLE_RADIO_MENU_ITEM,
-  /*
+  /**
    * A specialized pane that has a glass pane and a layered pane as its
    * children.
    */
   ROLE_ROOT_PANE,
-  /* The header for a row of data */
+  /** The header for a row of data */
   ROLE_ROW_HEADER,
-  /*
+  /**
    * An object usually used to allow a user to incrementally view a large
-   * amount of data.
+   * amount of data by moving the bounds of a viewport along a one-dimensional axis.
    */
   ROLE_SCROLL_BAR,
-  /*
+  /**
    * An object that allows a user to incrementally view a large amount
-   * of information.
+   * of information.  ROLE_SCROLL_PANE objects are usually accompanied by
+   * ROLE_SCROLL_BAR controllers, on which the RELATION_CONTROLLER_FOR and
+   * RELATION_CONTROLLED_BY reciprocal relations are set; \see 
+   * Accessibility::RelationSet.
    */
   ROLE_SCROLL_PANE,
-  /*
+  /**
    * An object usually contained in a menu to provide a visible and
    * logical separation of the contents in a menu.
    */
   ROLE_SEPARATOR,
-  /* An object that allows the user to select from a bounded range */
+  /** An object that allows the user to select from a bounded range */
   ROLE_SLIDER,
-  /* 
+  /** 
    * An object which allows one of a set of choices to be selected, 
-   * and which displays the current choice.
+   * and which displays the current choice.  Unlike ROLE_SCROLL_BAR,
+   * ROLE_SLIDER objects need not control 'viewport'-like objects.
    */
   ROLE_SPIN_BUTTON,
-  /* A specialized panel that presents two other panels at the same time. */
+  /** A specialized panel that presents two other panels at the same time. */
   ROLE_SPLIT_PANE,
-  /* Object displays non-quantitative status information (c.f. ROLE_PROGRESS_BAR) */
+  /** Object displays non-quantitative status information (c.f. ROLE_PROGRESS_BAR) */
   ROLE_STATUS_BAR,
-  /* An object used to repesent information in terms of rows and columns. */
+  /** An object used to repesent information in terms of rows and columns. */
   ROLE_TABLE,
+  /** A 'cell' or discrete child within a Table. \note Table cells need not have ROLE_TABLE_CELL, 
+   * other RoleType values are valid as well.  */
   ROLE_TABLE_CELL,
+  /** An object which labels a particular column in a Table. */
   ROLE_TABLE_COLUMN_HEADER,
+  /** An object which labels a particular row in a Table. Table rows and columns may also be 
+   * labelled via the RELATION_LABEL_FOR/RELATION_LABELLED_BY relationships; 
+   * \see Accessibility::RelationSet. */
   ROLE_TABLE_ROW_HEADER,
-  /* Object allows menu to be removed from menubar and shown in its own window. */
+  /** Object allows menu to be removed from menubar and shown in its own window. */
   ROLE_TEAROFF_MENU_ITEM,
-  /* An object that emulates a terminal */
+  /** An object that emulates a terminal */
   ROLE_TERMINAL,
-  /* An object that presents text to the user */
+  /** An object that presents text to the user, of nonspecific type. */
   ROLE_TEXT,
-  /*
+  /**
    * A specialized push button that can be checked or unchecked, but does
    * not procide a separate indicator for the current state.
    */
   ROLE_TOGGLE_BUTTON,
-  /*
+  /**
    * A bar or palette usually composed of push buttons or toggle buttons
    */
   ROLE_TOOL_BAR,
-  /*
+  /**
    * An object that provides information about another object
    */
   ROLE_TOOL_TIP,
-  /* An object used to repsent hierarchical information to the user. */
+  /** An object used to repsent hierarchical information to the user. */
   ROLE_TREE,
-  /* An object that presents both tabular and hierarchical info to the user */
+  /** An object that presents both tabular and hierarchical info to the user */
   ROLE_TREE_TABLE,
-  /*
+  /**
    * The object contains some Accessible information, but its role is
-   * not known.
+   * not known.  
    */
   ROLE_UNKNOWN,
-  /* An object usually used in a scroll pane. */
+  /** An object usually used in a scroll pane, or to otherwise clip a larger object or 
+   * content renderer to a specific onscreen viewport. */
   ROLE_VIEWPORT,
-  /* A top level window with no title or border */
+  /** A ¨top level window¨ with no title or border. */
   ROLE_WINDOW,
-  /* 
+  /** 
    * means that the role for this item is known, but not included in the 
    * core enumeration 
    */
   ROLE_EXTENDED,
-  /* An object that serves as a document header. */
+  /** An object that serves as a document header. */
   ROLE_HEADER,
-  /* An object that serves as a document footer. */
+  /** An object that serves as a document footer. */
   ROLE_FOOTER,
-  /* An object which is contains a paragraph of text content. */
+  /** An object which is contains a single paragraph of text content. \see also ROLE_TEXT. */
   ROLE_PARAGRAPH,
-  /*
+  /**
    * An object which describes margins and tab stops, etc. 
    * for text objects which it controls 
    * (should have CONTROLLER_FOR relation to such). 
    */
   ROLE_RULER,
-  /*
+  /**
    * An object corresponding to the toplevel accessible of an 
    * application, which may contain ROLE_FRAME objects or other
    * accessible objects.  Children of AccessibleDesktop objects 
    * are generally ROLE_APPLICATION objects.
    */
   ROLE_APPLICATION,
-  /*
+  /**
    * The object is a dialog or list containing items for insertion 
    * into an entry widget, for instance a list of words for completion 
    * of a text entry.
    */
   ROLE_AUTOCOMPLETE,
-  /*
+  /**
    * The object is an editable text object in a toolbar.
    */
   ROLE_EDITBAR,
-  /*
+  /**
    * The object is an embedded component container.  This role is a 
    * "grouping" hint that the contained objects share a context which is 
    * different from the container in which this accessible is embedded.
@@ -282,7 +294,86 @@ module Accessibility {
    * for embedding of out-of-process component, "panel applets", etc.
    */
   ROLE_EMBEDDED,
-  /* not a valid role, used for finding end of enumeration. */
+
+  /**
+   * The object is a link to some other content, for instance to a URI in this or another 
+   * document.  ROLE_LINK can occur primarily in two situations; as the role of an 
+   * object returned via the Hypertext::getLink, or, more importantly, as the role
+   * of a standalone object that implements the Hypertext interface but points to only
+   * one link object. 
+   *
+   * @note NOT SURE ABOUT THIS ONE, the description makes it sound pretty ropy.
+   * Why aren't links just identified via the Hypertext interface?  For non-textual
+   * hyperlinks (as allowed in XHTML 2.0), shouldn't this role be ROLE_IMAGE
+   * or ROLE_ICON?  
+   *
+   * @since AT-SPI 1.7.0
+   */
+  ROLE_LINK,
+  /**
+   * The object is a component whose textual content may be entered or modified by the user,
+   * provided STATE_EDITABLE is present.  
+   * @note a readonly ROLE_ENTRY object (i.e. where STATE_EDITABLE is not present) implies a
+   * read-only ¨text field¨ in a form, as opposed to a title, label, or caption.
+   *
+   * @since AT-SPI 1.7.0
+   */
+  ROLE_ENTRY,
+  /**
+   * The object is a graphical depiction of quantitative data.  It may contain multiple
+   * subelements whose attributes and/or description may be queried to obtain both the
+   * quantitative data and information about how the data is being presented.
+   * The LABELLED_BY relation is particularly important in interpreting objects of this type,
+   * as is the accessible-description property.  
+   * @see ROLE_CAPTION
+   *
+   * @since AT-SPI 1.7.0
+   */
+  ROLE_CHART,
+  /**
+   * The object contains descriptive information, usually textual, about another user interface
+   * element such as a table, chart, or image.
+   *
+   * @since AT-SPI 1.7.0
+   */
+  ROLE_CAPTION,
+  /**
+   * The object is a visual frame or container which contains a view of document content.  
+   * Document frames may occur within another Document instance, in which case the second 
+   * document may be said to be embedded in the containing instance.  HTML frames are
+   * often ROLE_DOCUMENT_FRAME.  Either this object, or a singleton descendant, should implement
+   * the Document interface.
+   *
+   * @since AT-SPI 1.7.0
+   */
+  ROLE_DOCUMENT_FRAME,
+  /**
+   * The object serves as a heading for content which follows it in a document.
+   * The 'heading level' of the heading, if availabe,  may be obtained by
+   * querying the object's attributes. 
+   *
+   * @since AT-SPI 1.7.0
+   */
+  ROLE_HEADING,
+  /**
+   * The object is a containing instance which encapsulates a page of 
+   * information.  ROLE_PAGE is used in documents and content which support
+   * a paginated navigation model.
+   * 
+   * @since AT-SPI 1.7.0
+   */
+  ROLE_PAGE,
+  /**
+   * The object is a containing instance of document content which constitutes
+   * a particular 'logical' section of the document.  The type of content within
+   * a section, and the nature of the section division itself, may be obtained
+   * by querying the object's attributes.  Sections may be nested.
+   *
+   * @since AT-SPI 1.7.0
+   */
+  ROLE_SECTION,
+
+  /** not a valid role, used for finding end of enumeration. */
   ROLE_LAST_DEFINED
   };
 };
diff --git a/idl/Accessibility_Selection.idl b/idl/Accessibility_Selection.idl
index a14e505e..e059ed9a 100644
--- a/idl/Accessibility_Selection.idl
+++ b/idl/Accessibility_Selection.idl
@@ -24,15 +24,108 @@
 
 module Accessibility {
 
+  /** 
+   * An interface which indicates that an object exposes a 'selection' model,
+   * allowing the selection of one or more of its children.  Read-only Selection
+   * instances are possible, in which case the interface is used to programmatically
+   * determine the selected-ness of its children.  A selected child has ::State::STATE_SELECTED,
+   * and a child which may hypothetically be selected (though possibly not programmatically
+   * selectable) has ::State::STATE_SELECTABLE.
+   * @note Events emitted by implementors of Selection include:
+   * \li \c "object:selection-changed" An instance of Selection has undergone a change in the
+   *                                  'selected-ness' of its children, i.e. had a selection added,
+   *                                  removed, and/or modified.  Usually accompanied by
+   *                                  corresponding \c "object:state-changed:selected" events
+   *                                  from the corresponding children, unless the children are
+   *                                  previously un-queried via AT-SPI and the Selection instance
+   *                                  has ::State::STATE_MANAGES_DESCENDANTS.
+   **/
   interface Selection : Bonobo::Unknown {
+    /**
+     * The number of children of a Selection implementor which are
+     *        currently selected.
+     */
     readonly attribute long nSelectedChildren;
+    /**
+     * Get the i-th selected Accessible child of a Selection.
+     * @note \c selectedChildIndex refers to the index in the list of 
+     * 'selected' children as opposed to the more general 'child index'
+     * of an object;  as such it generally differs from that used in
+     * Accessible::getChildAtIndex() or returned by
+     * Accessible::getIndexInParent(). 
+     * \c selectedChildIndex must lie between 0
+     * and Selection::nSelectedChildren-1, inclusive.
+     * @param selectedChildIndex: a long integer indicating which of the 
+     * selected children of an object is being requested.
+     * @returns a pointer to a selected Accessible child object,
+     *          specified by \c selectedChildIndex.
+     */
     Accessible getSelectedChild (in long selectedChildIndex);
+   /**
+    * Add a child to the selected children list of a Selection.
+    * @note For Selection implementors that only allow
+    *       single selections, this call may result in the
+    *       replacement of the (single) current
+    *       selection.  The call may return \c False if
+    *       the child is not selectable (i.e. does not have ::State::STATE_SELECTABLE), 
+    *       if the user does not have permission to change the selection, 
+    *       or if the Selection instance does not have ::State::STATE_SENSITIVE.
+    *
+    * @param childIndex: a long integer indicating which child of the
+    *              Selection is to be selected.
+    *
+    * @returns \c True if the child was successfully selected, 
+    *          \c False otherwise.
+    */
     boolean selectChild (in long childIndex);
+   /**
+    * Remove a child to the selected children list of a Selection.
+    * @note \c childIndex is the index in the selected-children list,
+    *       not the index in the parent container.  \c selectedChildIndex in this
+    *       method, and \c childIndex in Selection::selectChild
+    *       are asymmettric.
+    *
+    * @param selectedChildIndex: a long integer indicating which of the 
+    *         selected children of the Selection is to be deselected.  The index
+    *         is a zero-offset index into the 'selected child list', not
+    *         a zero-offset index into the list of all children of the Selection.
+    *
+    * @returns \c True if the child was successfully deselected, 
+    *          \c False otherwise.
+    *
+    * @see deselectChild
+    **/    
     boolean deselectSelectedChild (in long selectedChildIndex);
+   /**
+    * Determine whether a particular child of an Selection implementor
+    *        is currently selected.  Note that \c childIndex is the zero-offset
+    *        index into the standard Accessible container's list of children.
+    *
+    * @param childIndex: an index into the Selection's list of children.
+    *
+    * @returns \c True if the specified child is currently selected,
+    *          \c False otherwise.
+    **/
     boolean isChildSelected (in long childIndex);
+    /**
+     * Attempt to select all of the children of a Selection implementor.
+     * Not all Selection implementors support this operation (for instance, 
+     * implementations which support only "single selection" do not support this operation).
+     *
+     * @returns \c True if successful, \c False otherwise.
+     */
     boolean selectAll ();
+    /**
+     * Attempt to clear all selections (i.e. deselect all children) of a Selection.
+     * Not all Selection implementations allow the removal of all selections.
+     *
+     * @note this operation may fail if the object must have at least one selected child,
+     * if the user does not have permission to change the selection, or if the Selection
+     * does not have ::State::STATE_SENSITIVE.
+     *
+     * @returns \c True if the selections were successfully cleared, \c False otherwise.
+     */
     boolean clearSelection ();
-
     /**
      * unImplemented:
      *
diff --git a/idl/Accessibility_State.idl b/idl/Accessibility_State.idl
index 9c43288f..effbda3d 100644
--- a/idl/Accessibility_State.idl
+++ b/idl/Accessibility_State.idl
@@ -27,113 +27,244 @@ module Accessibility {
 
   enum StateType {
   STATE_INVALID,
-  /* Indicates a window is currently the active window */
+  /** Indicates a window is currently the active window, or is an active subelement within a container or table **/
   STATE_ACTIVE,
-  /* Indicates that the object is armed */
+  /** Indicates that the object is armed */
   STATE_ARMED,
-  /* Indicates the current object is busy */
+  /** 
+   * Indicates the current object is busy, i.e. onscreen representation is in the process of changing, or
+   * the object is temporarily unavailable for interaction due to activity already in progress.
+   */
   STATE_BUSY,
-  /* Indicates this object is currently checked */
+  /** Indicates this object is currently checked */
   STATE_CHECKED,
-  /* Indicates this object is collapsed */
+  /** Indicates this object is collapsed */
   STATE_COLLAPSED,
-  /* Indicates that this object no longer contains a backing widget */
+  /** Indicates that this object no longer has a valid backing widget 
+   * (for instance, if its peer object has been destroyed) */
   STATE_DEFUNCT,
-  /* Indicates the user can change the contents of this object */
+  /** Indicates the user can change the contents of this object */
   STATE_EDITABLE,
-  /* Indicates that this object is enabled */
+  /** Indicates that this object is enabled, i.e. that it currently reflects some application state. 
+   * Objects that are "greyed out" may lack this state, and may lack the STATE_SENSITIVE if direct user
+   * interaction cannot cause them to acquire STATE_ENABLED.  @see STATE_SENSITIVE.
+   */
   STATE_ENABLED,
-  /* Indicates this object allows progressive disclosure of its children */
+  /** Indicates this object allows progressive disclosure of its children */
   STATE_EXPANDABLE,
-  /* Indicates this object its expanded */
+  /** Indicates this object its expanded */
   STATE_EXPANDED,
-  /*
+  /**
    * Indicates this object can accept keyboard focus, which means all
    * events resulting from typing on the keyboard will normally be passed
    * to it when it has focus
    */
   STATE_FOCUSABLE,
-  /* Indicates this object currently has the keyboard focus */
+  /** Indicates this object currently has the keyboard focus */
   STATE_FOCUSED,
-  /* Indicates that the object has an associated tooltip */
+  /** Indicates that the object has an associated tooltip */
   STATE_HAS_TOOLTIP,
-  /* Indicates the orientation of thsi object is horizontal */
+  /** Indicates the orientation of thsi object is horizontal */
   STATE_HORIZONTAL,
-  /* Indicates this object is minimized and is represented only by an icon */
+  /** Indicates this object is minimized and is represented only by an icon */
   STATE_ICONIFIED,
-  /*
+  /**
    * Indicates something must be done with this object before the user can
    * interact with an object in a different window.
    */
   STATE_MODAL,
-  /* Indicates this (text) object can contain multiple lines of text */
+  /** Indicates this (text) object can contain multiple lines of text */
   STATE_MULTI_LINE,
-  /*
+  /**
    * Indicates this object allows more than one of its children to be
-   * selected at the same time
+   * selected at the same time, or in the case of text objects, 
+   * that the object supports non-contiguous text selections.
    */
   STATE_MULTISELECTABLE,
-  /* Indicates this object paints every pixel within its rectangular region. */
+  /** Indicates this object paints every pixel within its rectangular region.
+   * It also indicates an alpha value of unity, if it supports alpha blending. 
+   */
   STATE_OPAQUE,
-  /* Indicates this object is currently pressed */
+  /** Indicates this object is currently pressed */
   STATE_PRESSED,
-  /* Indicates the size of this object is not fixed */
+  /** Indicates the size of this object's size is not fixed */
   STATE_RESIZABLE,
-  /*
+  /**
    * Indicates this object is the child of an object that allows its
    * children to be selected and that this child is one of those children
    * that can be selected.
    */
   STATE_SELECTABLE,
-  /*
+  /**
    * Indicates this object is the child of an object that allows its
    * children to be selected and that this child is one of those children
    * that has been selected.
    */
   STATE_SELECTED,
-  /* Indicates this object is sensitive */
+  /** Indicates this object is sensitive, e.g. to user interaction. 
+   * STATE_SENSITIVE usually accompanies STATE_ENABLED for user-actionable controls,
+   * but may be found in the absence of STATE_ENABLED if the current visible state of the 
+   * control is "disconnected" from the application state.  In such cases, direct user interaction
+   * can often result in the object gaining STATE_SENSITIVE, for instance if a user makes 
+   * an explicit selection using an object whose current state is ambiguous or undefined.
+   * @see STATE_ENABLED, STATE_INDETERMINATE. */
   STATE_SENSITIVE,
-  /*
+  /**
    * Indicates this object, the object's parent, the object's parent's
-   * parent, and so on, are all visible
+   * parent, and so on, are all 'shown' to the end-user, i.e.
+   * subject to "exposure" if blocking or obscuring objects do not interpose
+   * between this object and the top of the window stack.
    */
   STATE_SHOWING,
-  /* Indicates this (text) object can contain only a single line of text */
+  /** Indicates this (text) object can contain only a single line of text */
   STATE_SINGLE_LINE,
-  /* Indicates that this object's index within parent information may be invalid */
+  /** Indicates that the information returned for this object may no longer be
+   * synchronized with the application state.  This can occur if the object has STATE_TRANSIENT,
+   * and can also occur towards the end of the object peer's lifecycle. */
   STATE_STALE,
-  /* Indicates this object is transient */
+  /** Indicates this object is transient */
   STATE_TRANSIENT,
-  /* Indicates the orientation of this object is vertical */
+  /** Indicates the orientation of this object is vertical; for example this state may appear on 
+   * such objects as scrollbars, text objects (with vertical text flow), separators, etc.
+   */
   STATE_VERTICAL,
-  /* Indicates this object is visible */
+  /** Indicates this object is visible, e.g. has been explicitly marked for exposure to the user.
+   * @note: STATE_VISIBLE is no guarantee that the object is actually unobscured on the screen, only
+   * that it is 'potentially' visible, barring obstruction, being scrolled or clipped out of the 
+   * field of view, or having an ancestor container that has not yet made visible.
+   * A widget is potentially onscreen if it has both STATE_VISIBLE and STATE_SHOWING.
+   * The absence of STATE_VISIBLE and STATE_SHOWING is semantically equivalent to saying 
+   * that an object is 'hidden'.
+   */
   STATE_VISIBLE,
-  /*
+  /**
    * Indicates that "active-descendant-changed" event is sent when children
    * become 'active' (i.e. are selected or navigated to onscreen).  Used to
    * prevent need to enumerate all children in very large containers, like
-   * tables.
+   * tables.  The presence of STATE_MANAGES_DESCENDANTS is an indication to the client.
+   * that the children should not, and need not, be enumerated by the client.
+   * Objects implementing this state are expected to provide relevant state
+   * notifications to listening clients, for instance notifications of visibility
+   * changes and activation of their contained child objects, without the client 
+   * having previously requested references to those children.
    */
   STATE_MANAGES_DESCENDANTS,
-  /*
-   * Indicates that a check box is in a state other than checked or not checked.
+  /**
+   * Indicates that a check box or other boolean indicator is in a state other than 
+   * checked or not checked.  This usually means that the boolean value reflected or 
+   * controlled by the object does not apply consistently to the entire current context.
+   * For example, a checkbox for the "Bold" attribute of text may have STATE_INDETERMINATE
+   * if the currently selected text contains a mixture of weight attributes.  
+   * In many cases interacting with a STATE_INDETERMINATE object will cause 
+   * the context's corresponding boolean attribute to be homogenized, whereupon the object
+   * will lose STATE_INDETERMINATE and a corresponding state-changed event will be fired.
    */
   STATE_INDETERMINATE,
+  /**
+   * Indicates that user interaction with this object is 'required' from the user, 
+   * for instance before completing the processing of a form.
+   */
+  STATE_REQUIRED,
+  /**
+   * Indicates that an object's onscreen content is truncated, e.g. a text value in a spreadsheet cell. 
+   * @since AT-SPI 1.7.0.
+   */
+  STATE_TRUNCATED,
+  /**
+   * Indicates this object's visual representation is dynamic, not static.
+   * This state may be applied to an object during an animated 'effect' and 
+   * be removed from the object once its visual representation becomes static.
+   * @note some applications, notably content viewers, may not be able to detect
+   * all kinds of animated content.  Therefore the absence of this state should not
+   * be taken as definitive evidence that the object's visual representation is
+   * static; this state is advisory.
+   *
+   * @since AT-SPI 1.7.0
+   */
+  STATE_ANIMATED,
+  /**
+   * This object has indicated an error condition due to failure of input
+   * validation.  For instance, a form control may acquire this state in response
+   * to invalid or malformed user input.
+   *
+   * @since AT-SPI 1.7.0 
+   */
+  STATE_INVALID_ENTRY,
+  /**
+   * This state indicates that the object in question implements some form of ¨typeahead¨ or 
+   * pre-selection behavior whereby entering the first character of one or more sub-elements
+   * causes those elements to scroll into view or become selected.  Subsequent character input
+   * may narrow the selection further as long as one or more sub-elements match the string.
+   * This state is normally only useful and encountered on objects that implement Selection.
+   * In some cases the typeahead behavior may result in full or partial ¨completion¨ of 
+   * the data in the input field, in which case these input events may trigger text-changed
+   * events from the source.
+   *
+   * @since AT-SPI 1.7.0 
+   */
+  STATE_SUPPORTS_AUTOCOMPLETION,
+  /**
+   * This state indicates that the object in question supports text selection. 
+   * It should only be exposed on objects which implement the Text interface, 
+   * in order to distinguish this state from STATE_SELECTABLE, which infers that
+   * the object in question is a selectable child of an object which implements
+   * Selection.  While similar, text selection and subelement selection are
+   * distinct operations.
+   *
+   * @since AT-SPI 1.7.0 
+   */
+  STATE_SELECTABLE_TEXT,
+  /**
+   * This state indicates that the object in question is the 'default' interaction object 
+   * in a dialog, i.e. the one that gets activated if the user presses "Enter" when the
+   * dialog is initially posted.
+   *
+   * @since AT-SPI 1.7.0 
+   */
+  STATE_IS_DEFAULT,
 
+  /** This value of the enumeration should not be used as a parameter, it indicates the number of
+   * items in the StateType enumeration.
+   */
   STATE_LAST_DEFINED
   };
 
   typedef sequence <StateType> StateSeq;
 
+    /** 
+     * The StateSet interface encapsulates a collection of state information.
+     * It allows comparison of state information between object instances, and comparisons
+     * of an object's state with some hypothetical collection of states.
+     */
   interface StateSet : Bonobo::Unknown {
+
+    /** Query a StateSet for a specific StateType. 
+     * @param state the StateType being queried for.
+     * @returns \c TRUE if the StateSet contains StateType \a state.
+     */
     boolean 		contains (in StateType state);
+
+    /** Add a StateType to an existing StateSet, if not already present. */
     void		add (in StateType state);
+
+    /** Remove a StateType to an existing StateSet, if it is present. */ 
     void 		remove (in StateType state);
+
+    /** Compare two statesets for equivalence.
+     * @param stateSet the StateSet to be compared with this one.
+     * @returns \c TRUE if the two StateSet objects are composed of the same StateTypes. 
+     */
     boolean		equals (in StateSet stateSet);
-    /* returns a 'difference set' */
+
+    /** Compare two StateSet instances and obtain their differences.
+     * @returns a 'difference set', i.e. a StateSet consisting of those states 
+     * not shared by the two sets being compared. */
     StateSet            compare (in StateSet compareState);
+
+    /** @returns \c TRUE if the StateSet contains no states. */
     boolean		isEmpty ();
 
+    /** \cond */
     /* Private */
     StateSeq getStates ();
 
@@ -146,6 +277,7 @@ module Accessibility {
     void unImplemented2 ();
     void unImplemented3 ();
     void unImplemented4 ();
+    /** \endcond */
   };
 };
 
diff --git a/idl/Accessibility_StreamableContent.idl b/idl/Accessibility_StreamableContent.idl
index 4ca62bbf..c552a638 100644
--- a/idl/Accessibility_StreamableContent.idl
+++ b/idl/Accessibility_StreamableContent.idl
@@ -26,12 +26,91 @@ module Accessibility {
 
   typedef sequence<string> StringSeq;
 
+  /** 
+   * An interface whereby an object allows its backing content
+   * to be streamed to clients.  Negotiation of content type
+   * is allowed.  Clients may examine the backing data and
+   * transform, convert, or parse the content in order to
+   * present it in an alternate form to end-users.
+   *
+   * @note The StreamableContent interface is particularly useful for saving, 
+   * printing, or post-processing entire documents, or for persisting 
+   * alternate views of a document.
+   * If document content itself is being serialized, stored, or converted,
+   * then use of the StreamableContent interface can help address performance
+   * issues.  Unlike most AT-SPI/Accessibility interfaces, this interface
+   * is not strongly tied to the current user-agent view of the
+   * a particular document, but may in some cases give access to the 
+   * underlying model data.
+   */
   interface StreamableContent {
+
+      /** 
+       * Specifies the meaning of a seek 'offset'.  Not all SeekTypes are 
+       * supported by all StreamableContent data sources, for instance 
+       * some streams may not support seeking from the beginning or other
+       * types of 'backwards' seeks.
+       */
+      enum SeekType {
+	  SEEK_SET, /**< Seek from the start of the stream or data source.*/
+	  SEEK_CURRENT, /**< Seek relative to the current position. */
+	  SEEK_END /**< Seek from the end of the file, stream, or data source. */
+      };
+
+      /** 
+       * Indicates that a transmission error has occurred while 
+       * reading or seeking the stream or data source. 
+       */
+      exception IOError {
+	  string reason;
+      };
+      /** 
+       * Indicates that the requested operation is not supported by the stream instance.
+       */
+      exception NotSupported {
+	  string reason;
+      };
+
+      /**
+       * The operation is supported, but the current requestor does not have
+       * permission to t the request, for instance does not have permission to read 
+       * the stream.
+       */
+      exception NoPermission {
+	  string reason;
+      };
+
+      /**
+       * getContentTypes:
+       * @returns the list of available mimetypes for this object's content.
+       */
     StringSeq getContentTypes ();
+      /**
+       * Retrieve this object's content, in a format appropriate to a
+       * requested mimetype.
+       *
+       * @note the data is returned as an object of type ::Bonobo::Stream.
+       * The primary methods which are supported on Bonobo::Streams for the
+       * purposes of the ::StreamableContent API are \c seek and \c read.
+       * \c seek may not be supported for all mimetypes or
+       * all implementors.
+       * 
+       \verbatim
+        long Bonobo::Stream:seek (in long offset, in SeekType whence)
+                raises (NoPermission, IOError)
+        void Bonobo::Stream:read (in long count, out iobuf buffer)
+                raises (NoPermission, IOError)
+       \endverbatim
+       *  
+       * @see ::Bonobo::Stream
+       *
+       * @returns a ::Bonobo::Stream whose mimetype matches \a contentType,
+       *          if available, or \c NIL.
+       */
     Bonobo::Stream getContent (in string contentType);
-    /* methods used from Bonobo::Stream : seek, read.  Others unsupported. */
 
     /**
+     * \cond
      * unImplemented:
      *
      * placeholders for future expansion.
@@ -40,5 +119,6 @@ module Accessibility {
     void unImplemented2 ();
     void unImplemented3 ();
     void unImplemented4 ();
+      /** \endcond */
   };
 };
diff --git a/idl/Accessibility_Table.idl b/idl/Accessibility_Table.idl
index 66e0301c..0e2ee672 100644
--- a/idl/Accessibility_Table.idl
+++ b/idl/Accessibility_Table.idl
@@ -26,34 +26,273 @@ module Accessibility {
 
 typedef sequence<long> LongSeq;
 
+  /**
+   * An interface used by containers whose contained data is arranged in 
+   * a "tabular" (i.e.\ row-column) fashion.  Tables may resemble a two-dimensional
+   * grid, as in a spreadsheet, or may feature objects which span multiple rows and/or
+   * columns, but whose bounds are aligned on a row/column matrix.  Thus, the Table
+   * interface may be used to represent "spreadsheets" as well as "frames".
+   *
+   * Objects within tables are children of the Table instance, and they may be referenced
+   * either via a child index or via a row/column pair.  
+   * Their role may be ROLE_TABLE_CELL, but table 'cells' may have other roles as well.
+   * These 'cells' may implement other interfaces, such as Text, Action, Image, 
+   * and Component, and should do so as appropriate to their onscreen representation
+   * and/or behavior.
+   */
  interface Table : Bonobo::Unknown {
+   /** 
+    * The total number of rows in this table (including empty rows),
+    * exclusive of any rows which are programmatically hidden.
+    * Rows which are merely scrolled out of view are included.
+    */
    readonly attribute long nRows;
+   /** 
+    * The total number of columns in this table (including empty columns),
+    * exclusive of columns which are programmatically hidden.
+    * Columns which are scrolled out of view or clipped by the current
+    * viewport are included. 
+    */
    readonly attribute long nColumns;
+   /**
+    * An Accessible which represents of a caption for a Table.
+    **/
    readonly attribute Accessible caption;
+   /**
+    * An accessible object which summarizes the contents of a Table.
+    * This object is frequently itself a Table instance, albeit a simplified one.
+    */
    readonly attribute Accessible summary;
+   /** 
+    * The number of rows currently selected.  
+    * A selected row is one in which all included cells are selected.
+    * @note Not all tables support row selection.
+    */
    readonly attribute long nSelectedRows;
+   /** 
+    * The number of columns currently selected.  
+    * A selected column is one in which all included cells are selected.
+    * @note Not all tables support column selection.
+    */
    readonly attribute long nSelectedColumns;
-
+   /**
+    * Get the table cell at the specified row and column indices.
+    * @note    To get the accessible object at a particular (x, y) screen coordinate,
+    *          use Accessible::getAccessibleAtPoint ().
+    *
+    * @param row: the specified table row, zero-indexed.
+    * @param column: the specified table column, zero-indexed.
+    *
+    * @returns an Accessible object representing the specified table cell.
+    **/   
    Accessible getAccessibleAt (in long row, in long column);
+   /**
+    * Get the 1-D child index corresponding to the specified 2-D row and column indices.
+    * @note    To get the accessible object at a particular (x, y) screen coordinate,
+    *          use Accessible::getAccessibleAtPoint.
+    *
+    * @param row: the specified table row, zero-indexed.
+    * @param column: the specified table column, zero-indexed.
+    *
+    * @see getRowAtIndex, getColumnAtIndex
+    *
+    * @returns a long integer which serves as the index of a specified cell in the
+    *          table, in a form usable by Accessible::getChildAtIndex.
+    **/   
    long getIndexAt (in long row, in long column);
+   /**
+    * Get the table row index occupied by the child at a particular 1-D child index.
+    *
+    * @param index: the specified child index, zero-indexed.
+    *
+    * @see getIndexAt(), getColumnAtIndex()
+    *
+    * @returns a long integer indicating the first row spanned by the child of a
+    *          table, at the specified 1-D (zero-offset) \c index.
+    **/
    long getRowAtIndex (in long index);
+   /**
+    * Get the table column index occupied by the child at a particular 1-D child index.
+    *
+    * @param index: the specified child index, zero-indexed.
+    *
+    * @see getIndexAt(), getRowAtIndex()
+    *
+    * @returns a long integer indicating the first column spanned by the child of a
+    *          table, at the specified 1-D (zero-offset) \c index.
+    **/
    long getColumnAtIndex (in long index);
+   /**
+    * Get a text description of a particular table row.  This differs from
+    * AccessibleTable_getRowHeader, which returns an Accessible.
+    * @param row: the specified table row, zero-indexed.
+    *
+    * @returns a UTF-8 string describing the specified table row, if available.
+    **/ 
    string getRowDescription (in long row);
+   /**
+    * Get a text description of a particular table column.  This differs from
+    * AccessibleTable_getColumnHeader, which returns an Accessible.
+    * @param column: the specified table column, zero-indexed.
+    *
+    * @returns a UTF-8 string describing the specified table column, if available.
+    **/ 
    string getColumnDescription (in long column);
+   /**
+    * Get the number of rows spanned by the table cell at the specific row and column.
+    * (some tables can have cells which span multiple rows and/or columns).
+    *
+    * @param row: the specified table row, zero-indexed.
+    * @param column: the specified table column, zero-indexed.
+    *
+    * @returns a long integer indicating the number of rows spanned by the specified cell.
+    **/
    long getRowExtentAt (in long row, in long column);
+   /**
+    * Get the number of columns spanned by the table cell at the specific row and column.
+    * (some tables can have cells which span multiple rows and/or columns).
+    *
+    * @param row: the specified table row, zero-indexed.
+    * @param column: the specified table column, zero-indexed.
+    *
+    * @returns a long integer indicating the number of columns spanned by the 
+    * specified cell.
+    **/
    long getColumnExtentAt (in long row, in long column);
+   /**
+    * Get the header associated with a table row, if available.  This differs from
+    * getRowDescription, which returns a string.
+    *
+    * @param row: the specified table row, zero-indexed.
+    *
+    * @returns an Accessible representatin of the specified table row, if available.
+    **/
    Accessible getRowHeader (in long row);
+   /**
+    * Get the header associated with a table column, if available, as an 
+    * instance of Accessible.  This differs from
+    * getColumnDescription, which returns a string.
+    *
+    * @param column: the specified table column, zero-indexed.
+    *
+    * @returns an Accessible representatin of the specified table column, if available.
+    **/
    Accessible getColumnHeader (in long column);
+   /**
+    * Obtain the indices of all rows which are currently selected.  
+    * @note Not all tables support row selection.
+    *
+    * @returns a sequence of integers comprising the indices of rows currently selected.
+    **/
    LongSeq getSelectedRows ();
+   /**
+    * Obtain the indices of all columns which are currently selected.  
+    * @note Not all tables support column selection.
+    *
+    * @returns a sequence of integers comprising the indices of columns currently selected.
+    **/
    LongSeq getSelectedColumns ();
+   /**
+    * Determine whether a table row is selected.  
+    * @note Not all tables support row selection.
+    *
+    * @param row: the row being queried.
+    *
+    * @returns \c True if the specified row is currently selected, \c False if not.
+    **/
    boolean isRowSelected (in long row);
+   /**
+    * Determine whether a table column is selected.  
+    * @note Not all tables support column selection.
+    *
+    * @param column: the column being queried.
+    *
+    * @returns \c True if the specified column is currently selected, \c False if not.
+    **/
    boolean isColumnSelected (in long column);
+   /**
+    * Determine whether the cell at a specific row and column is selected.
+    * @param row a row occupied by the cell whose state is being queried.
+    * @param column a column occupied by the cell whose state is being queried.
+    *
+    * @returns \c True if the specified cell is currently selected, 
+    * \c False if not.
+    **/
    boolean isSelected (in long row, in long column);
+   /**
+    * Select the specified row, adding it to the current row selection,
+    * if the table's selection model permits it.
+    *
+    * @param row
+    * @note Possible reasons for addRowSelection to return \c False
+    * include:
+    * \li The table does not support Selection
+    * \li The table row includes cells which do not have STATE_SELECTABLE
+    * \li The table does not support selection by row
+    * \li The table does not support selection of multiple rows, and
+    * one row is already selected.
+    * \li The table does not support non-contiguous selections (i.e.
+    * does not include STATE_MULTISELECTABLE), and the specified row
+    * would result in selection of non-contiguous rows.
+    * \li The table does not support user-instigated selection.
+    *
+    * @returns \c True if the specified row was successfully selected, 
+    * \c False if not. 
+    **/
    boolean addRowSelection (in long row);
+   /**
+    * Select the specified column, adding it to the current column selection,
+    * if the table's selection model permits it.
+    *
+    * @param column
+    * @note Possible reasons for addColumnSelection to return \c False
+    * include:
+    * \li The table does not support Selection
+    * \li The table column includes cells which do not have STATE_SELECTABLE
+    * \li The table does not support selection by column
+    * \li The table does not support selection of multiple columns, and
+    * one column is already selected.
+    * \li The table does not support non-contiguous selections (i.e.
+    * does not include STATE_MULTISELECTABLE), and the specified column
+    * would result in selection of non-contiguous columns.
+    * \li The table does not support user-instigated selection.
+    *
+    * @returns \c True if the specified column was successfully selected, 
+    * \c False if not. 
+    **/
    boolean addColumnSelection (in long column);
+   /**
+    * Remove the specified row from current row selection,
+    * if the table's selection model permits it.
+    *
+    * @param row
+    * @note Possible reasons for removeRowSelection to return \c False
+    * include:
+    * \li The table does not support user-instigated Selection
+    * \li The table has no selected rows or does not support deselection by row
+    *
+    * @returns \c True if the specified row was successfully de-selected, 
+    * \c False if not. 
+    **/
    boolean removeRowSelection (in long row);
+   /**
+    * Remove the specified column from current column selection,
+    * if the table's selection model permits it.
+    *
+    * @param column
+    * @note Possible reasons for removeColumnSelection to return \c False
+    * include:
+    * \li The table does not support user-instigated modification of
+    * selection state
+    * \li The table has no selected columns or does not support 
+    * deselection by column.
+    *
+    * @returns \c True if the specified column was successfully de-selected, 
+    * \c False if not. 
+    **/
    boolean removeColumnSelection (in long column);
-    /**
+
+    /** \cond
      * unImplemented:
      *
      * placeholders for future expansion.
@@ -66,5 +305,6 @@ typedef sequence<long> LongSeq;
     void unImplemented6 ();
     void unImplemented7 ();
     void unImplemented8 ();
+    /** \endcond */
   };
 };
diff --git a/idl/Accessibility_Text.idl b/idl/Accessibility_Text.idl
index d0ea1f38..9afb8556 100644
--- a/idl/Accessibility_Text.idl
+++ b/idl/Accessibility_Text.idl
@@ -22,14 +22,44 @@
 
 module Accessibility {
 
+  /**
+   * Specifies the boundary conditions determining a run of text as returned from
+   * getTextAtOffset, getTextAfterOffset, and getTextBeforeOffset.
+   */
   enum TEXT_BOUNDARY_TYPE {
-    TEXT_BOUNDARY_CHAR,
-    TEXT_BOUNDARY_WORD_START,
-    TEXT_BOUNDARY_WORD_END,
-    TEXT_BOUNDARY_SENTENCE_START,
-    TEXT_BOUNDARY_SENTENCE_END,
-    TEXT_BOUNDARY_LINE_START,
-    TEXT_BOUNDARY_LINE_END
+    TEXT_BOUNDARY_CHAR,/**< Text is bounded by this character only. 
+			* Start and end offsets differ by one, by definition, for this value. 
+			*/
+    TEXT_BOUNDARY_WORD_START,/**< Boundary condition is start of a word; i.e. range is from start of
+			      * one word to the start of another word. 
+			      */
+    TEXT_BOUNDARY_WORD_END,/**< Boundary condition is the end of a word; i.e. range is from 
+			    * the end of one word to the end of another. 
+			    * @note some locales may not distinguish between words and
+			    * characters or glyphs, in particular those locales which use
+			    * wholly or partially ideographic character sets.  In these cases,
+			    * characters may be returned in lieu of multi-character substrings.
+			    */
+    TEXT_BOUNDARY_SENTENCE_START,/**< Boundary condition is start of a sentence, as determined 
+				*  by the application. 
+				*  @note Some locales or character sets may not include explicit sentence
+				*  delimiters, so this boundary type can not always be honored.
+				*  Some locales will return lines of text instead of grammatical sentences.
+				  */
+    TEXT_BOUNDARY_SENTENCE_END,/**< Boundary condition is end of a sentence, as determined by the application, 
+				*  including the sentence-delimiting character, for instance '.'
+				*  @note Some locales or character sets may not include explicit sentence
+				*  delimiters, so this boundary type can not always be honored.
+				*  Some locales will return lines of text instead of grammatical sentences.
+				*/
+    TEXT_BOUNDARY_LINE_START,/**< Boundary condition is the start of a line; i.e. range is 
+			      * from start of one line to the start of another.  This generally 
+			      * means that an end-of-line character will appear at the end of the range. 
+			      */
+    TEXT_BOUNDARY_LINE_END /**< Boundary condition is the end of a line; i.e. range is
+			    * from start of one line to the start of another.  This generally 
+			    * means that an end-of-line character will be the first character of the range. 
+			    */
   };
 
   /**
@@ -41,13 +71,56 @@ module Accessibility {
    **/
   enum TEXT_CLIP_TYPE {
     TEXT_CLIP_NONE,
-    TEXT_CLIP_MIN,
-    TEXT_CLIP_MAX,
-    TEXT_CLIP_BOTH
+    TEXT_CLIP_MIN,/**< characters/glyphs clipped by the minimum coordinate are omitted */
+    TEXT_CLIP_MAX,/**< characters/glyphs which intersect the maximum coordinate are omitted */
+    TEXT_CLIP_BOTH /**< only glyphs falling entirely within the region bounded by min and max are retained. */
   };
 
+    /** 
+     * The text interface should be implemented by objects which place textual information onscreen as character
+     * strings or glyphs.  The text interface allows access to textual content, including display attributes and
+     * semantic hints associated with runs of text, and access to bounding box information for glyphs and substrings.
+     * It also allows portions of textual content to be selected, if the object's StateSet includes
+     * STATE_SELECTABLE_TEXT. 
+     *
+     * In some cases a Text object may have, as its content, an empty string.  In particular this can
+     * occur in the case of Hypertext objects which do not display explicitly textual information onscreen,
+     * as Hypertext is derived from the Text interface.  @see Hypertext.
+     *
+     * Typographic and semantic attributes of onscreen textual content, for instance typeface, weight, 
+     * language, and such qualities as 'emphasis' or 'blockquote', are represented as text attributes.
+     * Contiguous sequences of characters over which these attributes are unchanged are referred to as
+     * "attribute runs", and are available via Text::getAttributeRun.  Where possible, implementing clients
+     * will report textual attributes which are the same over the entire text object, for instance those
+     * inherited from a default or document-scope style, via getDefaultAttributes instead of reporting them
+     * explicitly for each character.  Therefore, for any span of text, the attributes in effect are the union
+     * of the set returned by Text::getDefaultAttributes, and the set returned at a particular character
+     * offset via Text::getAttributeRun.
+     *
+     * @note Events that may be emitted by instances of Text include:
+     * \li \c "object:text-attributes-changed" The attributes of a range of text, or the range over 
+     *         which attributes apply, has changed.
+     * \li \c "object:text-changed" The text content of this object has changed.
+     * \li \c "object:text-bounds-changed" The character bounds of a text object have changed, 
+     *         for instance in response to a reformatting or reflow operation.
+     * \li \c "object:text-caret-moved" The character offset of the text caret (visible or notional) within
+     *         this object has changed.  Events of this type may also be generated when an onscreen
+     *         text caret appears or disappears.
+     * \li \c "object:text-selection-changed" The range or number of text selections within this text object
+     *         has changed.
+     *
+     * @note In some cases, objects which are not onscreen may implement Text, but if such objects
+     * implement Component, their potential visibility should be examined (via comparison with STATE_VISIBLE 
+     * and STATE_SHOWING) before exposing them to the user.  Objects which implement Text but not Component 
+     * may be encountered in special-purpose interfaces or as special ¨accessibility¨ extensions to visual 
+     * interfaces to allow non-graphical access to application features.  These instances should be considered 
+     * the exception, rather than the rule.
+     */
   interface Text : Bonobo::Unknown {
 
+    /** A structure used to define a continguous range of text, including its 
+     * (unattributed) textual content. 
+     **/
     struct Range {
       long startOffset;
       long endOffset; 
@@ -56,40 +129,263 @@ module Accessibility {
     };
     
     typedef sequence<Range> RangeList;
-    
+
+    /** The total current number of characters in the Text object, 
+     * including whitespace and non-spacing characters.  
+     **/
     readonly attribute long characterCount;
+
+    /** The current offset of the text caret in the Text object.  
+     * This caret may be virtual, e.g. non-visual and notional-only, but if an
+     * onscreen representation of the caret position is visible, it will correspond to this offset.
+     * The caret offset is given as a character offset, as opposed to a byte offset into 
+     * a text buffer or a column offset. 
+     **/
     readonly attribute long caretOffset;
+
+      /**
+       * Obtain all or part of the onscreen textual content of a Text object.  If endOffset is specified as 
+       * "-1", then this method will return the entire onscreen textual contents of the Text object.
+       * @note 'onscreen' in this context means "potentially onscreen", this method does not perform any sort 
+       * of coordinate visibility clipping or window-stack-ordering clipping.  The text thus reported 
+       * corresponds to the text which would be presented onscreen if the object implementing the Text interface
+       * were entirely unobscured. 
+       * @returns the textual content of the current Text object beginning startOffset (inclusive) 
+       * up to but not including the character at endOffset.
+       **/
     string getText (in long startOffset, in long endOffset);
+
+      /** Programmatically move the text caret (visible or virtual, as above) to a given position. 
+       * @param offset a long int indicating the desired character offset.  Not all implementations of
+       * Text will honor setCaretOffset requests, so the return value below should be checked by the client.
+       * @returns \c TRUE if the request was carried out, or \c FALSE if the caret could not be moved to 
+       * the requested position.
+       **/
     boolean setCaretOffset (in long offset);
+
+      /**
+       * Obtain a subset of the text content of an object which entirely precedes \c offset,
+       * delimited by character, word, line, or sentence boundaries as specified by \c type.  The
+       * starting and ending offsets of the resulting substring are returned in \c startOffset
+       * and \c endOffset.  By definition, if such a substring exists, \c endOffset is less than or
+       * equal to \c offset.
+       * @param offset the offset from which the substring search begins.
+       * @param type the text-boundary delimiter which determines whether the returned text constitures
+       *        a character, word, line, or sentence (and possibly attendant whitespace), 
+       *        and whether the start or ending of such a substring forms the boundary condition.
+       * @param startOffset back-filled with the starting offset of the resulting substring, if one exists.
+       * @param endOffset back-filled with the offset of the character immediately following the resulting
+       *                  substring, if one exists.
+       * @see TEXT_BOUNDARY_TYPE
+       * @returns a string which is a substring of the text content of the object, delimited by the
+       * specified boundary condition.
+       */
     string getTextBeforeOffset (in long offset, in TEXT_BOUNDARY_TYPE type,
 				out long startOffset, out long endOffset);
+      /**
+       * Obtain a subset of the text content of an object which includes the specified \c offset, 
+       * delimited by character, word, line, or sentence boundaries as specified by \c type.  The
+       * starting and ending offsets of the resulting substring are returned in \c startOffset
+       * and \c endOffset.  
+       * @param offset the offset from which the substring search begins, and which must 
+       *        lie within the returned substring.
+       * @param type the text-boundary delimiter which determines whether the returned text constitures
+       *        a character, word, line, or sentence (and possibly attendant whitespace), 
+       *        and whether the start or ending of such a substring forms the boundary condition.
+       * @param startOffset back-filled with the starting offset of the resulting substring, if one exists.
+       * @param endOffset back-filled with the offset of the character immediately following the resulting
+       *                  substring, if one exists.
+       * @see TEXT_BOUNDARY_TYPE
+       * @returns a string which is a substring of the text content of the object, delimited by the
+       * specified boundary condition.
+       */
     string getTextAtOffset (in long offset, in TEXT_BOUNDARY_TYPE type,
 			    				out long startOffset, out long endOffset);
+      /**
+       * Obtain a subset of the text content of an object which entirely follows \c offset,
+       * delimited by character, word, line, or sentence boundaries as specified by \c type.  The
+       * starting and ending offsets of the resulting substring are returned in \c startOffset
+       * and \c endOffset.  By definition, if such a substring exists, \c startOffset must be greater than
+       * \c offset.
+       * @param offset the offset from which the substring search begins, and which must 
+       *        lie before the returned substring.
+       * @param type the text-boundary delimiter which determines whether the returned text constitures
+       *        a character, word, line, or sentence (and possibly attendant whitespace), 
+       *        and whether the start or ending of such a substring forms the boundary condition.
+       * @param startOffset back-filled with the starting offset of the resulting substring, if one exists.
+       * @param endOffset back-filled with the offset of the character immediately following the resulting
+       *                  substring, if one exists.
+       * @see TEXT_BOUNDARY_TYPE
+       * @returns a string which is a substring of the text content of the object, delimited by the
+       * specified boundary condition.
+       */
     string getTextAfterOffset (in long offset, in TEXT_BOUNDARY_TYPE type,
 			       				out long startOffset, out long endOffset);
+      /**
+       * @returns an unsigned long integer whose value corresponds to the UCS-4 representation of the
+       * character at the specified text offset, or 0 if offset is out of range.
+       */
     unsigned long getCharacterAtOffset (in long offset);  /* long instead of wchar, 
 							   * to allow unicode chars > 16 bits 
 							   */
+    /** 
+     * Get the string value of a named attribute at a given offset, if defined.
+     * @param offset the offset of the character for which the attribute run is to be obtained.
+     * @param attributeName the name of the attribute for which the value is to be returned, if defined.
+     * @param startOffset back-filled with the offset of the first character in the attribute run
+     * containing the character at \c offset.
+     * @param endOffset back-filled with the offset of the first character past the end of the
+     * attribute run containing the character at \c offset.
+     * @param defined back-filled with \c True if the attributeName has a defined value at \c offset,
+     * \c False otherwise.
+     * @returns the value of attribute (name-value pair) corresponding to "name", if defined. 
+     **/
+    string getAttributeValue (in long offset, in string attributeName,
+			      out long startOffset,
+			      out long endOffset,
+			      out boolean defined);
+    /** 
+     * getAttributes is deprecated in favor of getAttributeRun.
+     * @returns the attributes at offset, as a semicolon-delimited set of colon-delimited name-value pairs. 
+     * @see getAttributeRun
+     **/
     string getAttributes (in long offset,
 			  out long startOffset, out long endOffset);
+      /** 
+       * Deprecated in favor of getDefaultAttributeSet.
+       * @returns the attributes which apply to the entire text content, but which were not explicitly
+       * specified by the content creator.
+       * @see getDefaultAttributeSet
+       **/
     string getDefaultAttributes ();
+      /**
+       * Obtain a the bounding box, as x, y, width, and height, of the character or glyph at a particular 
+       * character offset in this object's text content.  The coordinate system in which the results are
+       * reported is specified by coordType.  If an onscreen glyph corresponds to multiple character offsets,
+       * for instance if the glyph is a ligature, the bounding box reported will include the entire glyph and
+       * therefore may apply to more than one character offset.
+       * @param offset the character offset of the character or glyph being queried.
+       * @param x the minimum horizontal coordinate of the bounding box of the glyph representing 
+       *          the character at \c offset.
+       * @param y the minimum vertical coordinate of the bounding box of the glyph representing 
+       *          the character at \c offset.
+       * @param width the horizontal extent of the bounding box of the glyph representing 
+       *          the character at \c offset.
+       * @param height the vertical extent of the bounding box of the glyph representing 
+       *          the character at \c offset.
+       * @param coordType If 0, the results will be reported in screen coordinates, i.e. in pixels
+       *                  relative to the upper-left corner of the screen, with the x axis pointing right
+       *                  and the y axis pointing down.
+       *                  If 1, the results will be reported relative to the containing toplevel window,
+       *                  with the x axis pointing right and the y axis pointing down.
+       **/
     void getCharacterExtents (in long offset, out long x, out long y, out long width, out long height, in short coordType);
+      /** 
+       * Get the offset of the character at a given onscreen coordinate.  The coordinate system used to interpret
+       * x and y is determined by parameter coordType.
+       * @param x
+       * @param y
+       * @param coordType if 0, the input coordinates are interpreted relative to the entire screen, if 1,
+       *                  they are relative to the toplevel window containing this Text object.
+       * @returns the text offset (as an offset into the character array) of the glyph whose onscreen bounds contain the point x,y, or -1 if the point is outside the bounds of any glyph.
+       **/
     long getOffsetAtPoint (in long x, in long y, in short coordType);
+      /**
+       * Obtain the number of separate, contiguous selections in the current Text object.
+       * Text objects which do not implement selection of discontiguous text regions will always
+       * return '0' or '1'.  Note that "contiguous" is defined by continuity of the offsets, i.e.
+       * a text 'selection' is defined by a start/end offset pair.  In the case of bidirectional text,
+       * this means that a continguous selection may appear visually discontiguous, and vice-versa.
+       *
+       * @returns the number of contiguous selections in the current Text object.
+       **/
     long getNSelections ();
+      /**
+       * The result of calling getSelection with an out-of-range selectionNum (i.e. for a selection 
+       * which does not exist) is not strictly defined, but should set endOffset equal to startOffset.
+       **/
     void getSelection (in long selectionNum, out long startOffset, out long endOffset);
+      /**
+       * The result of calling addSelection on objects which already have one selection present, and which
+       * do not include STATE_MULTISELECTABLE, is undefined, other than the return value.
+       * @returns \c True of the selection was successfully added, \c False otherwise. Selection may
+       * fail if the object does not support selection of text (see STATE_SELECTABLE_TEXT), if the
+       * object does not support multiple selections and a selection is already defined, or for other reasons
+       * (for instance if the user does not have permission to copy the text into the relevant selection 
+       * buffer).
+       **/
     boolean addSelection (in long startOffset, in long endOffset);
+      /**
+       * Deselect the text contained in the specified selectionNum, if such a selection
+       * exists, otherwise do nothing.  Removal of a non-existant selectionNum has no effect.
+       * @returns \c True if the selection was successfully removed, \c False otherwise.
+       **/
     boolean removeSelection (in long selectionNum);
+      /**
+       * Modify an existing selection's start or ending offset. 
+       *
+       * Calling setSelection for a selectionNum that is not already defined has no effect.
+       * The result of calling setSelection with a selectionNum greater than 0 for objects that
+       * do not include STATE_MULTISELECTABLE is undefined.
+       * @param selectionNum indicates which of a set of non-contiguous selections to modify.
+       * @param startOffset the new starting offset for the selection
+       * @param endOffset the new ending offset for the selection
+       * @returns \c True if the selection corresponding to selectionNum is successfully modified, 
+       *             \c False otherwise.
+       **/
     boolean setSelection (in long selectionNum, in long startOffset, in long endOffset);
+      /**
+       * Obtain the bounding box which entirely contains a given text range.
+       * Negative values may be returned for the bounding box parameters in the event
+       * that all or part of the text range is offscreen or not mapped to the screen.
+       * @param startOffset the offset of the first character in the specified range.
+       * @param endOffset the offset of the character immediately after the last 
+       *        character in the specified range.
+       * @param x an integer parameter which is back-filled with the minimum
+       *        horizontal coordinate of the resulting bounding box.
+       * @param y an integer parameter which is back-filled with the minimum
+       *        vertical coordinate of the resulting bounding box.
+       * @param width an integer parameter which is back-filled with the
+       *        horizontal extent of the bounding box.
+       * @param height an integer parameter which is back-filled with the
+       *        vertical extent of the bounding box.
+       * @param coordType If 0, the above coordinates are reported in pixels relative to
+       *        corner of the screen; if 1, the coordinates are reported relative to the
+       *        corner of the containing toplevel window.
+       **/
     void    getRangeExtents (in long startOffset, in long endOffset, 
 			     out long x, out long y, 
 			     out long width, out long height, in short coordType);
+
+      /**
+       * Return the text content within a bounding box, 
+       * as a list of Range structures.
+       * Depending on the TEXT_CLIP_TYPE parameters, glyphs which are clipped by the
+       * bounding box (i.e. which lie partially inside and partially outside it)
+       * may or may not be included in the ranges returned.  
+       * @note This method may be of particular interest to screen review algorithms.
+       * @see TEXT_CLIP_TYPE.
+       * @param x the minimum x ( i.e. leftmost)  coordinate of the bounding box.
+       * @param y the minimum y coordinate of the bounding box.
+       * @param width the horizontal size of the bounding box.  The rightmost bound of the bounding box
+       *        is (x + width);
+       * @param height the vertical size of the bounding box.  The maximum y value of the bounding box
+       *        is (y + height);
+       * @param coordType If 0, the above coordinates are interpreted as pixels relative to
+       *        corner of the screen; if 1, the coordinates are interpreted as pixels relative to the
+       *        corner of the containing toplevel window.
+       * @param xClipType determines whether text which intersects the bounding box in the x direction
+       *        is included.
+       * @param yClipType determines whether text which intersects the bounding box in the y direction
+       *        is included.
+       **/
     RangeList getBoundedRanges (in long x, in long y, 
 				in long width, in long height, 
 				in short coordType, 
 				in TEXT_CLIP_TYPE xClipType, 
 				in TEXT_CLIP_TYPE yClipType);
 
-    /**
+    /** \cond
      * unImplemented:
      *
      * placeholders for future expansion.
@@ -97,5 +393,7 @@ module Accessibility {
     void unImplemented ();
     void unImplemented2 ();
     void unImplemented3 ();
+    void unImplemented4 ();
+    /** \endcond **/
   };
 };
diff --git a/idl/Accessibility_Value.idl b/idl/Accessibility_Value.idl
index 82de7710..4531879d 100644
--- a/idl/Accessibility_Value.idl
+++ b/idl/Accessibility_Value.idl
@@ -22,13 +22,37 @@
 
 module Accessibility {
 
+   /**
+    * An interface supporting controls which allow a
+    * one-dimensional, scalar quantity to be modified or which
+    * reflect a scalar quantity. (If STATE_EDITABLE is not present, 
+    * the valuator is treated as "read only".
+    *
+    * @note Events generated by Image instances include:
+    * \li \c "object:value-changed"
+    */
   interface Value : Bonobo::Unknown {
+    /**
+     * The minimum value allowed by this valuator.
+     */
     readonly attribute double minimumValue;
+    /**
+     * The maximum value allowed by this valuator.
+     */
     readonly attribute double maximumValue;
+    /**
+     * The smallest incremental change which this valuator allows.
+     * If 0, the incremental changes to the valuator are 
+     * limited only by the precision of a double precision value
+     * on the platform.
+     */
     readonly attribute double minimumIncrement;
+    /**
+     * The current value of the valuator.
+     */
     attribute double currentValue;
 
-    /**
+    /** \cond
      * unImplemented:
      *
      * placeholders for future expansion.
@@ -37,5 +61,6 @@ module Accessibility {
     void unImplemented2 ();
     void unImplemented3 ();
     void unImplemented4 ();
+    /** \endcond */
   };
 };