Added documentation.

Libs/PluginFramework/ctkCaseInsensitiveString.h

@@ -27,20 +27,75 @@
 
 #include <ctkPluginFrameworkExport.h>
 
+/**
+ * ctkCaseInsensitiveString wraps a QString and can be
+ * used in Qt container classes as a key type representing
+ * case insensitive strings. However, case is preserved when
+ * retrieving the actual QString.
+ */
 class CTK_PLUGINFW_EXPORT ctkCaseInsensitiveString
 {
 
 public:
 
+  /**
+   * Wraps a null QString.
+   */
   ctkCaseInsensitiveString();
+
+  /**
+   * Wraps the given character sequence.
+   *
+   * @param str The characters to be wrapped by this ctkCaseInsensitiveString
+   */
   ctkCaseInsensitiveString(const char* str);
+
+  /**
+   * Wraps the given QString.
+   *
+   * @param str The QString to be wrapped by this ctkCaseInsensitiveString
+   */
   ctkCaseInsensitiveString(const QString& str);
+
+  /**
+   * Copy constructor.
+   *
+   * @param str The ctkCaseInsensitiveString instance to copy.
+   */
   ctkCaseInsensitiveString(const ctkCaseInsensitiveString& str);
 
+  /**
+   * Assignment operator.
+   *
+   * @param str The ctkCaseInsensitiveString instance which should be
+   *        assigned.
+   */
   ctkCaseInsensitiveString& operator=(const ctkCaseInsensitiveString& str);
+
+  /**
+   * String comparison ignoring case.
+   *
+   * @param str The string with which to compare this instance.
+   * @return <code>true</code> if both strings are equal after being
+   *         converted to lower case strings, <code>false</code> otherwise.
+   */
   bool operator==(const ctkCaseInsensitiveString& str) const;
+
+  /**
+   * Less than operator ignoring case.
+   *
+   * @param str The string with which to compare this instance.
+   * @return <code>true</code> if the lower case variant of the
+   *         current string is lexicographically less then
+   *         the lower case variant of <code>str</code>, <code>false</code>
+   *         otherwise.
+   */
   bool operator<(const ctkCaseInsensitiveString& str) const;
 
+  /**
+   * Converts this ctkCaseInsensitiveString instance to a QString,
+   * preserving the original case.
+   */
   operator QString() const;
 
 private:
@@ -48,6 +103,11 @@ private:
   QString str;
 };
 
+/**
+ * Returns a hash value for the lower case string.
+ *
+ * @param str The string to be hashed.
+ */
 uint CTK_PLUGINFW_EXPORT qHash(const ctkCaseInsensitiveString& str);
 
 CTK_PLUGINFW_EXPORT QDataStream& operator<<(QDataStream &out, const ctkCaseInsensitiveString& str);

Libs/PluginFramework/ctkLDAPSearchFilter.h

@@ -32,23 +32,113 @@
 
 class ctkLDAPSearchFilterData;
 
+/**
+ * An <a href="http://www.ietf.org/rfc/rfc1960.txt">RFC 1960</a>-based Filter.
+ *
+ * <p>
+ * A {@code ctkLDAPSearchFilter} can be used numerous times to determine if the match
+ * argument matches the filter string that was used to create the {@code ctkLDAPSearchFilter}.
+ * <p>
+ * Some examples of LDAP filters are:
+ *
+ * \verbatim
+ * "(cn=Babs Jensen)"
+ * "(!(cn=Tim Howes))"
+ * "(&(" + ctkPluginConstants::OBJECTCLASS + "=Person)(|(sn=Jensen)(cn=Babs J*)))"
+ *  "(o=univ*of*mich*)"
+ * \endverbatim
+ *
+ * \see "CTK Wiki for a description of the filter string syntax." TODO!
+ * \threadsafe
+ */
 class CTK_PLUGINFW_EXPORT ctkLDAPSearchFilter {
 
 public:
 
   ctkLDAPSearchFilter();
+
+  /**
+   * Creates a <code>ctkLDAPSearchFilter</code> object. This <code>ctkLDAPSearchFilter</code>
+   * object may be used to match a <code>ctkServiceReference</code> object or a
+   * <code>ctkDictionary</code> object.
+   *
+   * <p>
+   * If the filter cannot be parsed, an std::invalid_argument will be
+   * thrown with a human readable message where the filter became unparsable.
+   *
+   * @param filter The filter string.
+   * @return A <code>ctkLDAPSearchFilter</code> object encapsulating the filter string.
+   * @throws std::invalid_argument If <code>filter</code> contains an invalid
+   *         filter string that cannot be parsed.
+   * @see "Framework specification for a description of the filter string syntax." TODO!
+   */
   ctkLDAPSearchFilter(const QString& filter);
+
   ctkLDAPSearchFilter(const ctkLDAPSearchFilter& other);
 
   ~ctkLDAPSearchFilter();
 
+  /**
+   * Filter using a service's properties.
+   * <p>
+   * This {@code ctkLDAPSearchFilter} is executed using the keys and values of the
+   * referenced service's properties. The keys are looked up in a case
+   * insensitive manner.
+   *
+   * @param reference The reference to the service whose properties are used
+   *        in the match.
+   * @return <code>true</code> if the service's properties match this
+   *         <code>ctkLDAPSearchFilter</code> <code>false</code> otherwise.
+   */
   bool match(const ctkServiceReference& reference) const;
+
+  /**
+   * Filter using a <code>ctkDictionary</code> with case insensitive key lookup. This
+   * <code>ctkLDAPSearchFilter</code> is executed using the specified <code>ctkDictionary</code>'s keys
+   * and values. The keys are looked up in a case insensitive manner.
+   *
+   * @param dictionary The <code>ctkDictionary</code> whose key/value pairs are used
+   *        in the match.
+   * @return <code>true</code> if the <code>ctkDictionary</code>'s values match this
+   *         filter; <code>false</code> otherwise.
+   */
   bool match(const ctkDictionary& dictionary) const;
+
+  /**
+   * Filter using a <code>ctkDictionary</code>. This <code>ctkLDAPSearchFilter</code> is executed using
+   * the specified <code>ctkDictionary</code>'s keys and values. The keys are looked
+   * up in a normal manner respecting case.
+   *
+   * @param dictionary The <code>ctkDictionary</code> whose key/value pairs are used
+   *        in the match.
+   * @return <code>true</code> if the <code>ctkDictionary</code>'s values match this
+   *         filter; <code>false</code> otherwise.
+   */
   bool matchCase(const ctkDictionary& dictionary) const;
 
+  /**
+   * Returns this <code>ctkLDAPSearchFilter</code>'s filter string.
+   * <p>
+   * The filter string is normalized by removing whitespace which does not
+   * affect the meaning of the filter.
+   *
+   * @return This <code>ctkLDAPSearchFilter</code>'s filter string.
+   */
   QString toString() const;
 
+  /**
+   * Compares this <code>ctkLDAPSearchFilter</code> to another <code>ctkLDAPSearchFilter</code>.
+   *
+   * <p>
+   * This implementation returns the result of calling
+   * <code>this->toString() == other.toString()</code>.
+   *
+   * @param other The object to compare against this <code>ctkLDAPSearchFilter</code>.
+   * @return Returns the result of calling
+   *         <code>this->toString() == other.toString()</code>.
+   */
   bool operator==(const ctkLDAPSearchFilter& other) const;
+
   ctkLDAPSearchFilter& operator=(const ctkLDAPSearchFilter& filter);
 
 protected: