improve QXmppDataForm documentation

2 files changed, 96 insertions, 5 deletions

diff --git a/src/QXmppDataForm.cpp b/src/QXmppDataForm.cpp
index 859f9a5f..b174157b 100644
--- a/src/QXmppDataForm.cpp
+++ b/src/QXmppDataForm.cpp
@@ -48,131 +48,209 @@ static field_type field_types[] = {
     {static_cast<QXmppDataForm::Field::Type>(-1), NULL},
 };
 
+/// Constructs a QXmppDataForm::Field of the specified \a type.
+///
+/// \param type
+
 QXmppDataForm::Field::Field(QXmppDataForm::Field::Type type)
     : m_type(type)
 {
 }
 
+/// Returns the field's description.
+
 QString QXmppDataForm::Field::description() const
 {
     return m_description;
 }
 
+/// Sets the field's description.
+///
+/// \param description
+
 void QXmppDataForm::Field::setDescription(const QString &description)
 {
     m_description = description;
 }
 
+/// Returns the field's key.
+
 QString QXmppDataForm::Field::key() const
 {
     return m_key;
 }
 
+/// Sets the field's key.
+///
+/// \param key
+
 void QXmppDataForm::Field::setKey(const QString &key)
 {
     m_key = key;
 }
 
+/// Returns the field's label.
+
 QString QXmppDataForm::Field::label() const
 {
     return m_label;
 }
 
+/// Sets the field's label.
+///
+/// \param label
+
 void QXmppDataForm::Field::setLabel(const QString &label)
 {
     m_label = label;
 }
 
+/// Returns the field's options.
+
 QList<QPair<QString, QString> > QXmppDataForm::Field::options() const
 {
     return m_options;
 }
 
+/// Sets the field's options.
+///
+/// \param options
+
 void QXmppDataForm::Field::setOptions(const QList<QPair<QString, QString> > &options)
 {
     m_options = options;
 }
 
+/// Returns true if the field is required, false otherwise.
+
 bool QXmppDataForm::Field::isRequired() const
 {
     return m_required;
 }
 
+/// Set to true if the field is required, false otherwise.
+///
+/// \param required
+
 void QXmppDataForm::Field::setRequired(bool required)
 {
     m_required = required;
 }
 
+/// Returns the field's type.
+
 QXmppDataForm::Field::Type QXmppDataForm::Field::type() const
 {
     return m_type;
 }
 
+/// Sets the field's type.
+///
+/// \param type
+
 void QXmppDataForm::Field::setType(QXmppDataForm::Field::Type type)
 {
     m_type = type;
 }
 
+/// Returns the field's value.
+
 QVariant QXmppDataForm::Field::value() const
 {
     return m_value;
 }
 
+/// Sets the field's value.
+///
+/// \param value
+
 void QXmppDataForm::Field::setValue(const QVariant &value)
 {
     m_value = value;
 }
 
+/// Constructs a QXmppDataForm of the specified \a type.
+///
+/// \param type
+
 QXmppDataForm::QXmppDataForm(QXmppDataForm::Type type)
     : m_type(type)
 {
 }
 
+/// Returns the form's fields.
+
 QList<QXmppDataForm::Field> QXmppDataForm::fields() const
 {
     return m_fields;
 }
 
+/// Returns the form's fields by reference.
+
 QList<QXmppDataForm::Field> &QXmppDataForm::fields()
 {
     return m_fields;
 }
 
+/// Sets the form's fields.
+///
+/// \param fields
+
 void QXmppDataForm::setFields(const QList<QXmppDataForm::Field> &fields)
 {
     m_fields = fields;
 }
 
+/// Returns the form's instructions.
+
 QString QXmppDataForm::instructions() const
 {
     return m_instructions;
 }
 
+/// Sets the form's instructions.
+///
+/// \param instructions
+
 void QXmppDataForm::setInstructions(const QString &instructions)
 {
     m_instructions = instructions;
 }
 
+/// Returns the form's title.
+
 QString QXmppDataForm::title() const
 {
     return m_title;
 }
 
+/// Sets the form's title.
+///
+/// \param title
+
 void QXmppDataForm::setTitle(const QString &title)
 {
     m_title = title;
 }
 
+/// Returns the form's type.
+
 QXmppDataForm::Type QXmppDataForm::type() const
 {
     return m_type;
 }
 
+/// Sets the form's type.
+///
+/// \param type
+
 void QXmppDataForm::setType(QXmppDataForm::Type type)
 {
     m_type = type;
 }
 
+/// Returns true if the form has an unknown type.
+
 bool QXmppDataForm::isNull() const
 {
     return m_type == QXmppDataForm::None;
diff --git a/src/QXmppDataForm.h b/src/QXmppDataForm.h
index f4abdb91..2d997846 100644
--- a/src/QXmppDataForm.h
+++ b/src/QXmppDataForm.h
@@ -38,9 +38,14 @@ class QDomElement;
 class QXmppDataForm
 {
 public:
+    /// \brief The QxmppDataForm::Field class represents a data form field
+    /// as defined by XEP-0004: Data Forms.
+    ///
+
     class Field
     {
     public:
+        /// This enum is used to describe a field's type.
         enum Type
         {
             BooleanField,
@@ -88,13 +93,19 @@ public:
         QVariant m_value;
     };
 
+    /// This enum is used to describe a form's type.
     enum Type
     {
-        None,
-        Form,
-        Submit,
-        Cancel,
-        Result,
+        None,   ///< Unknown form type
+        Form,   ///< The form-processing entity is asking the form-submitting
+                ///< entity to complete a form.
+        Submit, ///< The form-submitting entity is submitting data to the
+                ///< form-processing entity.
+        Cancel, ///< The form-submitting entity has cancelled submission
+                ///< of data to the form-processing entity.
+        Result, ///< The form-processing entity is returning data
+                ///< (e.g., search results) to the form-submitting entity,
+                ///< or the data is a generic data set.
     };
 
     QXmppDataForm(QXmppDataForm::Type type = QXmppDataForm::None);
@@ -114,8 +125,10 @@ public:
 
     bool isNull() const;
 
+    /// \cond
     void parse(const QDomElement &element);
     void toXml(QXmlStreamWriter *writer) const;
+    /// \endcond
 
 private:
     QString m_instructions;