Improving atspi-matchrule documentation.

diff --git a/atspi/atspi-matchrule.c b/atspi/atspi-matchrule.c
index 76415c2..d68cdb9 100644 (file)
--- a/atspi/atspi-matchrule.c
+++ b/atspi/atspi-matchrule.c
@@ -79,27 +79,41 @@ atspi_match_rule_class_init (AtspiMatchRuleClass *klass)
  * atspi_match_rule_new:
  *
  * @states: An #AtspiStateSet specifying the states to match or NULL if none.
+ *
  * @statematchtype: An #AtspiCollectionMatchType specifying how to interpret
  *                  @states.
+ *
  * @attributes: (element-type gchar* gchar*): A #GHashTable specifying
  *              attributes to match.
+ *
  * @attributematchtype: An #AtspiCollectionMatchType specifying how to
  *                      interpret @attributes.
+ *
  * @interfaces: (element-type gchar*): An array of interfaces to match, or
- *              NUL if not applicable.  Interface names should be specified
+ *              NULL if not applicable.  Interface names should be specified
  *              by their DBus names (org.a11y.Atspi.Accessible,
  *              org.a11y.Atspi.Component, etc).
+ *
  * @interfacematchtype: An #AtspiCollectionMatchType specifying how to
  *                      interpret @interfaces.
+ *
  * @roles: (element-type AtspiRole): A #GArray of roles to match, or NULL if
  *         not applicable.
+ *
  * @rolematchtype: An #AtspiCollectionMatchType specifying how to
  *                      interpret @roles.
- * @invert: Specifies whether results should be inverted.
- * TODO: Document this parameter better.
+ *
+ * @invert: if #TRUE, the match rule should be denied (inverted); if #FALSE,
+ * it should not. For example, if the match rule defines that a match is
+ * an object of ROLE_HEADING which has STATE_FOCUSABLE and a click action, 
+ * inverting it would match all objects that are not of ROLE_HEADING, 
+ * focusable and clickable at the same time.  
+ *
+ * Creates a new #AtspiMatchRule with specified @states, @attributes, 
+ * @interfaces, and @roles.
  *
  * Returns: (transfer full): A new #AtspiMatchRule.
- */
+ **/
 AtspiMatchRule *
 atspi_match_rule_new (AtspiStateSet *states,
                       AtspiCollectionMatchType statematchtype,