More API documentation tweaks.

diff --git a/libmapi++/attachment.h b/libmapi++/attachment.h
index 14122cdce2a2cb895bae2d88c1622089adc281cd..ee283152cfff25c52bc1e099e6448291ddc7840e 100644 (file)
--- a/libmapi++/attachment.h
+++ b/libmapi++/attachment.h
@@ -32,11 +32,21 @@ namespace libmapipp
 {
 class object;
 
-/// \brief This class represents a message attachment
+/**
+ * \brief This class represents a message %attachment
+ *
+ * A message can contain both text content, and also have attached
+ * (embedded) files and messages. This class represents the attachments
+ * for one messaage.
+ * 
+ * You may not need to create the attachments yourself, since you can 
+ * create a container with all the attachments using message::fetch_attachments().
+ */
 class attachment : public object {
        public:
                /** \brief Constructor
-                *  \param mapi_message message this attachment belongs to.
+                *
+                *  \param mapi_message the message that this attachment belongs to.
                 *  \param attach_num Attachment Number.
                 */
                attachment(message& mapi_message, const uint32_t attach_num) throw(mapi_exception)
@@ -99,14 +109,37 @@ class attachment : public object {
 
                }
 
-               /// \brief Get Attachment number.
+               /**
+                * \brief The %attachment number
+                */
                uint32_t get_num() const { return m_attach_num; }
 
+               /**
+                * \brief the contents of the %attachment
+                *
+                * \note the length of the array is given by get_data_size()
+                */
                const uint8_t* get_data() const  { return m_bin_data; }
+
+               /**
+                * \brief the size of the %attachment
+                *
+                * \return the size of the %attachment in bytes
+                */
                uint32_t get_data_size() const { return m_data_size; }
+
+               /**
+                * \brief the filename of the %attachment
+                *
+                * \note not all attachments have file names
+                *
+                * \return string containing the file name of the %attachment, if any
+                */
                std::string get_filename() const { return m_filename; }
 
-               /// Destructor
+               /**
+                * Destructor
+                */
                virtual ~attachment() throw()
                {
                        if (m_bin_data) delete m_bin_data;

diff --git a/libmapi++/folder.h b/libmapi++/folder.h
index 61a73fa779f67713ada06e85823053e2c43765c9..7516a2fe471c4331ed6d76a5c793b765a99c7783 100644 (file)
--- a/libmapi++/folder.h
+++ b/libmapi++/folder.h
@@ -33,28 +33,34 @@
 namespace libmapipp
 {
 
-/// This class represents a folder or container within Exchange
+/**
+ *  This class represents a %folder or container within Exchange
+ */
 class folder : public object {
        public:
                /**
-                       Pointer to a message
+                * Pointer to a message
                */
                typedef boost::shared_ptr<message>              message_shared_ptr;
+
                typedef std::vector<message_shared_ptr >        message_container_type;
 
                /**
-                       Pointer to a folder
+                * Pointer to a %folder
                */
                typedef boost::shared_ptr<folder>               folder_shared_ptr;
-               /**
-                       Hierarchy folders
 
-                       This is a vector (list) of child folders for a given folder
+               /**
+                * Hierarchy folders
+                *
+                * This is a vector (list) of child folders for a given %folder
                */
                typedef std::vector<folder_shared_ptr>          hierarchy_container_type;
 
-               /** \brief Constructor
-                * \param parent_folder The parent of this folder.
+               /** 
+                * \brief Constructor
+                *
+                * \param parent_folder The parent of this %folder.
                 * \param folder_id     This folder's id.
                */
                folder(object& parent_folder, const mapi_id_t folder_id) throw(mapi_exception) 
@@ -64,13 +70,17 @@ class folder : public object {
                                throw mapi_exception(GetLastError(), "folder::folder : OpenFolder");
                }
 
-               /** \brief Get Folder id.
+               /**
+                * \brief Obtain %folder id
+                *
                 * \return This folder's id.
                 */
                mapi_id_t get_id() const { return m_id; }
 
-               /** \brief Deletes a message that belongs to this folder
-                *  \param message_id The id of the message to delete.
+               /** 
+                * \brief Delete a message that belongs to this %folder
+                *
+                * \param message_id The id of the message to delete.
                 */
                void delete_message(mapi_id_t message_id) throw (mapi_exception)
                {
@@ -79,7 +89,8 @@ class folder : public object {
                }
 
                /**
-                * \brief Fetches all messages in this folder. 
+                * \brief Fetch all messages in this %folder
+                *
                 * \return A container of message shared pointers.
                 */
                message_container_type fetch_messages() throw(mapi_exception)
@@ -131,10 +142,10 @@ class folder : public object {
                }
 
                /**
-                * \brief Fetches all subfolders within this folder
-                * \return A container of folder shared pointers.
+                * \brief Fetch all subfolders within this %folder
+                *
+                * \return A container of %folder shared pointers.
                 */
-
                hierarchy_container_type fetch_hierarchy() throw(mapi_exception)
                {
                        mapi_object_t   hierarchy_table;
@@ -181,7 +192,9 @@ class folder : public object {
                         return hierarchy_container;
                }
 
-               /// Destructor
+               /**
+                * Destructor
+                */
                virtual ~folder() throw()
                {
                }

diff --git a/libmapi++/message.h b/libmapi++/message.h
index da455f897c16e4d5fdbf408c6a376873c1644898..101063223ffb0c0f6d0dd23358da4d0665108d76 100644 (file)
--- a/libmapi++/message.h
+++ b/libmapi++/message.h
@@ -33,10 +33,12 @@ namespace libmapipp
 {
 class object;
 class attachment;
+
 /** 
- * \brief This class represents a message in Exchange.\n
- * It is important to note that a message is not necessarily an email message.\n
- * It could be a contact, journal or anything else that is not a folder.\n
+ * \brief This class represents a %message in Exchange.
+ *
+ * It is important to note that a %message is not necessarily an email %message.
+ * It could be a contact, journal or anything else that is not a folder.
  */
 class message : public object {
        public:
@@ -45,9 +47,10 @@ class message : public object {
 
                /**
                 * \brief Constructor
-                * \param mapi_session The session to use to retrieve this message.
-                * \param folder_id The id of the folder this message belongs to.
-                * \param message_id The message id.
+                *
+                * \param mapi_session The session to use to retrieve this %message.
+                * \param folder_id The id of the folder this %message belongs to.
+                * \param message_id The %message id.
                 */
                message(session& mapi_session, const mapi_id_t folder_id, const mapi_id_t message_id) throw(mapi_exception) 
                : object(mapi_session, "message"), m_folder_id(folder_id), m_id(message_id)
@@ -57,18 +60,25 @@ class message : public object {
                }
 
                /**
-                * \brief Fetches all attachments in this message.
+                * \brief Fetches all attachments in this %message.
+                *
                 * \return A container of attachment shared pointers.
                 */
                attachment_container_type fetch_attachments();
 
-               /// \brief Get this message's ID.
+               /**
+                * \brief Get this %message's ID.
+                */
                mapi_id_t get_id() const { return m_id; }
 
-               /// \brief Get this message's parent folder ID.
+               /**
+                * \brief Get this message's parent folder ID.
+                */
                mapi_id_t get_folder_id() const { return m_folder_id; } 
 
-               /// Destructor
+               /**
+                * Destructor
+                */
                virtual ~message() throw()
                {
                }