TizenRefApp-6787 Prepare documentation for calendar-common/main/model #6 (Fetcher...

Change-Id: I8c26486103ea0e8395b0928374193107a56e4db7
Signed-off-by: Yevgeniy Kolomiets <y.kolomiets@samsung.com>

diff --git a/common/model/CalOriginalSchedule.h b/common/model/CalOriginalSchedule.h
index 26eae1a..fd66480 100644 (file)
--- a/common/model/CalOriginalSchedule.h
+++ b/common/model/CalOriginalSchedule.h
@@ -22,33 +22,100 @@
 #include "CalScheduleReminder.h"
 #include "CalScheduleRepeat.h"
 
+/**
+ * @brief The CalOriginalSchedule class represents original event record.
+ *
+ */
 class WAPP_ASSIST_EXPORT CalOriginalSchedule: public CalSchedule
 {
 public:
        CalOriginalSchedule(int year, int month);
        CalOriginalSchedule(calendar_record_h record);
+       CalOriginalSchedule(const CalOriginalSchedule&);
        virtual ~CalOriginalSchedule();
 
-       CalOriginalSchedule(const CalOriginalSchedule&);
-       const CalOriginalSchedule& operator=(const CalOriginalSchedule&);
+       const CalOriginalSchedule& operator=(const CalOriginalSchedule& obj);
 
-public:
-       virtual void setStart(const CalDateTime& startTime);
+       /**
+        * @brief Set start time to event.
+        *
+        * @param[in] startTime      event start time
+        *
+        */
+       virtual void setStart(const CalDateTime &startTime);
 
+       /**
+        * @brief Get reminders count.
+        *
+        * @return reminders count.
+        *
+        */
        virtual const int getRemindersCount() const;
-       virtual const CalScheduleRepeat& getRepeat() const;
-       virtual void setRepeat(const CalScheduleRepeat& repeat);
-       virtual void getReminder(const int nth, CalScheduleReminder& reminder);
-       virtual void setReminder(const int nth, const CalScheduleReminder& reminder);
-       virtual int addReminder(const CalScheduleReminder& reminder);
+
+       /**
+        * @brief Get event repeat.
+        *
+        * @return event repeat.
+        *
+        */
+       virtual const CalScheduleRepeat &getRepeat() const;
+
+       /**
+        * @brief Set repeat to event.
+        *
+        * @param[in] repeat      event repeat
+        *
+        */
+       virtual void setRepeat(const CalScheduleRepeat &repeat);
+
+       /**
+        * @brief Get event reminder by index.
+        *
+        * @param[in]  nth        reminder index
+        * @param[out] reminder   reminder
+        *
+        */
+       virtual void getReminder(const int nth, CalScheduleReminder &reminder);
+
+       /**
+        * @brief Set event reminder by index.
+        *
+        * @param[in] nth        reminder index
+        * @param[in] reminder   reminder to set
+        */
+       virtual void setReminder(const int nth, const CalScheduleReminder &reminder);
+
+       /**
+        * @brief Add reminder to event.
+        *
+        * @param[in] reminder   reminder to add
+        *
+        * @return 0 - success, -1 if failed.
+        *
+        */
+       virtual int addReminder(const CalScheduleReminder &reminder);
+
+       /**
+        * @brief Remove reminder by index.
+        *
+        * @param[in] nth        reminder index
+        *
+        */
        virtual void removeReminder(const int nth);
-       virtual void initialize(const char* tzid, const CalDateTime& startTime);
+
+       /**
+        * @brief Initialization.
+        *
+        * @param[in] tzid        time zone
+        * @param[in] startTime   event start time
+        *
+        */
+       virtual void initialize(const char *tzid, const CalDateTime &startTime);
 
 protected:
        int getInstanceCountBeforeDate(const CalDateTime& date) const;
        void truncateRepeatToBeforeDate(const CalDateTime& date);
 
-protected:
        virtual unsigned int getIndexProperty(void) const;
        virtual unsigned int getStartProperty(void) const;
        virtual unsigned int getEndProperty(void) const;

diff --git a/common/model/CalRecordBlockFetcher.cpp b/common/model/CalRecordBlockFetcher.cpp
index 981476a..362a119 100644 (file)
--- a/common/model/CalRecordBlockFetcher.cpp
+++ b/common/model/CalRecordBlockFetcher.cpp
@@ -17,6 +17,8 @@
 
 #include "CalRecordBlockFetcher.h"
 
+static bool __integrityCheck(calendar_record_h record);
+
 CalRecordBlockFetcher::CalRecordBlockFetcher(calendar_query_h query, bool fetchAllAtOnce) :
        __query(query),
        __fetchAllAtOnce(fetchAllAtOnce)
@@ -47,8 +49,6 @@ void CalRecordBlockFetcher::prefetch(bool fillBothBuffers)
                __fetch(__nextBlock);
 }
 
-static bool __integrityCheck(calendar_record_h record);
-
 calendar_record_h CalRecordBlockFetcher::getNext(bool autoFetch)
 {
 RETRY:

diff --git a/common/model/CalRecordBlockFetcher.h b/common/model/CalRecordBlockFetcher.h
index e7df7a6..13d43af 100644 (file)
--- a/common/model/CalRecordBlockFetcher.h
+++ b/common/model/CalRecordBlockFetcher.h
@@ -19,20 +19,45 @@
 #define _CAL_RECORD_BLOCK_FETCHER_H_
 
 #include <calendar.h>
-
 #include "CalCommon.h"
 
-class CalRecordBlockFetcher {
+/**
+ * @brief The CalRecordBlockFetcher class is a wrapper
+ *        for a calendar_list_h.
+ */
+class CalRecordBlockFetcher
+{
 public:
        CalRecordBlockFetcher(calendar_query_h query, bool fetchAllAtOnce = false);
        virtual ~CalRecordBlockFetcher();
-public:
+
+       /**
+        * @brief Prefetch events from calendar service.
+        *
+        * @param fillBothBuffers       prefetch current buffer or current and next
+        *
+        */
        void prefetch(bool fillBothBuffers);
+
+       /**
+        * @brief Get next event.
+        *
+        * @param[in] autoFetch     fetch next block automatically if true
+        *
+        * @return next event record.
+        *
+        */
        calendar_record_h getNext(bool autoFetch = false);
+
+       /**
+        * @brief Check whether block is ended.
+        *
+        */
        bool eof();
+
 private:
        void __fetch(calendar_list_h& batch);
-private:
+
        const calendar_query_h __query;
        const bool __fetchAllAtOnce;
        calendar_list_h __currentBlock;

diff --git a/common/model/CalSchedule.h b/common/model/CalSchedule.h
index bb03a7b..9b176a4 100644 (file)
--- a/common/model/CalSchedule.h
+++ b/common/model/CalSchedule.h
@@ -28,82 +28,395 @@
 #include "CalScheduleRepeat.h"
 
 #define CAL_SCHEDULE_REMINDERS_MAX 5
+
+/**
+ * @class CalSchedule
+ * @brief The %CalSchedule class is a base class of event.
+ */
 class WAPP_ASSIST_EXPORT CalSchedule
 {
 public:
+
+       /**
+        * @brief Schedule object type
+        */
        enum Type
        {
-               INVALID = -1,
-               ORIGINAL = 0, // _calendar_event
-               INSTANCE_NORMAL, // _calendar_instance_utime_calendar_book_extended
-               INSTANCE_ALLDAY, // _calendar_instance_localtime_calendar_book_extended
+               INVALID = -1,    /**<  Bad type                                            */
+               ORIGINAL = 0,    /**< _calendar_event                                      */
+               INSTANCE_NORMAL, /**< _calendar_instance_utime_calendar_book_extended      */
+               INSTANCE_ALLDAY, /**< _calendar_instance_localtime_calendar_book_extended  */
        };
-protected:
-       CalSchedule();
-       CalSchedule(calendar_record_h record);
-       virtual ~CalSchedule();
-
-       CalSchedule(const CalSchedule&);
-       const CalSchedule& operator=(const CalSchedule&);
 
-public:
-       // get
+       /**
+        * @brief Get object type
+        *
+        * @return object type, @see Type.
+        *
+        */
        Type getType() const;
+
+       /**
+        * @brief Get event ID.
+        *
+        * @return event ID.
+        *
+        */
        int getIndex() const;
-       void getFromToDisplayString(std::string& text) const;  // for detail marupStr ..
+
+       /**
+        * @brief Get start and end time as text.
+        *
+        * @param[out] text        text buffer
+        *
+        */
+       void getFromToDisplayString(std::string& text) const;
+
+       /**
+        * @brief Get start and end time as text.
+        *
+        * @param[out] text        text buffer
+        *
+        */
        void getFromToString(std::string& text) const;
-       void getFromToString(const CalDate& date, std::string& text) const;  // for list
 
-       void getDisplaySummary(const int stringLimit, std::string& text) const; //text  markupStr (elm_entry_utf8_to_markup)
+       /**
+        * @brief Get start and end time as text.
+        *
+        * @param[in]  date        date
+        * @param[out] text        text buffer
+        */
+       void getFromToString(const CalDate& date, std::string& text) const;
+
+       /**
+        * @brief Get event title.
+        *
+        * @param[in]  stringLimit   buffer size
+        * @param[out] text          text buffer
+        *
+        */
+       void getDisplaySummary(const int stringLimit, std::string& text) const;
+
+       /**
+        * @brief Get event title as one line.
+        *
+        * @param[in]  stringLimit   buffer size
+        * @param[out] text          text buffer
+        *
+        */
        void getDisplayTrimedSummary(const int stringLimit, std::string& text);
+
+       /**
+        * @brief Get event title.
+        *
+        * @return event title.
+        *
+        */
        const char* getSummary() const;
-       void getDisplayLocation(const int stringLimit, std::string& text) const; //text markupStr (elm_entry_utf8_to_markup)
+
+       /**
+        * @brief Get event location as text.
+        *
+        * @param[in]  stringLimit   buffer size
+        * @param[out] text          text buffer
+        *
+        */
+       void getDisplayLocation(const int stringLimit, std::string& text) const;
+
+       /**
+        * @brief Get event location as one line.
+        *
+        * @param[in]  stringLimit   buffer size
+        * @param[out] text          text buffer
+        *
+        */
        void getDisplayTrimedLocation(const int stringLimit, std::string& text);
+
+       /**
+        * @brief Get event location.
+        *
+        * @return event location.
+        *
+        */
        const char* getLocation() const;
+
+       /**
+        * @brief Get event calendar ID.
+        *
+        * @return calendar ID.
+        *
+        */
        int getBookId() const;
+
+       /**
+        * @brief Get event start time.
+        *
+        * @param[out] startTime       event start time
+        *
+        */
        void getStart(CalDateTime& startTime) const;
+
+       /**
+        * @brief Get event end time.
+        *
+        * @param[out]  endTime       event end time
+        * @param[in]   isAdjustive
+        *
+        */
        void getEnd(CalDateTime& endTime, bool isAdjustive = false) const;
+
+       /**
+        * @brief Get end time for complex list model.
+        *
+        * @param[out]  endTime        end time for complex list model
+        *
+        */
        void getEndForComplexList(CalDateTime& endTime) const;
-       void getDisplayDescription(std::string& text) const; //text     markupStr (elm_entry_utf8_to_markup)
+
+       /**
+        * @brief Get event description.
+        *
+        * @param[out] text     event description
+        *
+        */
+       void getDisplayDescription(std::string& text) const;
+
+       /**
+        * @brief Get event description.
+        *
+        * @return event description.
+        *
+        */
        const char* getDescription() const;
+
+       /**
+        * @brief Get event time zone.
+        *
+        * @return event time zone.
+        *
+        */
        const char* getTimeZone() const;
+
+       /**
+        * @brief Get event UID.
+        *
+        * @return event UID.
+        *
+        */
        const char* getUid() const;
 
-       // set
+       /**
+        * @brief Set event title.
+        *
+        * @param summary      event title
+        *
+        */
        void setSummary(const char* summary);
+
+       /**
+        * @brief Set event location.
+        *
+        * @param location           event location
+        *
+        */
        void setLocation(const char* location);
+
+       /**
+        * @brief Set start time.
+        *
+        * @param startTime      event start time
+        *
+        */
        virtual void setStart(const CalDateTime& startTime);
+
+       /**
+        * @brief Set end time.
+        *
+        * @param endTime      event end time
+        *
+        */
        virtual void setEnd(const CalDateTime& endTime);
+
+       /**
+        * @brief Set event description.
+        *
+        * @param description       event description
+        *
+        */
        void setDescription(const char* description);
+
+       /**
+        * @brief Set event time zone.
+        *
+        * @param timezone       event time zone
+        *
+        */
        void setTimeZone(const char* timezone);
+
+       /**
+        * @brief Set event Calendar ID.
+        *
+        * @param bookId       Calendar ID
+        *
+        */
        void setBookId(const int bookId);
+
+       /**
+        * @brief Set event UID
+        *
+        * @param UID           event UID.
+        *
+        */
        void setUid(const char* uid);
 
-       // reminders
+       /**
+        * @brief Check whether event has remainder reminders.
+        *
+        * @return true if has, otherwise false.
+        *
+        */
        virtual const bool hasReminder() const;
+
+       /**
+        * @brief Get event reminders count.
+        *
+        * @return event reminders count
+        *
+        */
        virtual const int getRemindersCount() const;
+
+       /**
+        * @brief Get event reminder by index.
+        *
+        * @param[in]  nth        reminder index
+        * @param[out] reminder   reminder
+        *
+        */
        virtual void getReminder(const int nth, CalScheduleReminder& reminder);
+
+       /**
+        * @brief Set reminder to event by index.
+        *
+        * @param[in]  nth        reminder index
+        * @param[in]  reminder   reminder
+        */
        virtual void setReminder(const int nth, const CalScheduleReminder& reminder);
+
+       /**
+        * @brief Add reminder to event.
+        *
+        * @param reminder        reminder to add
+        *
+        * @return operation result.
+        *
+        */
        virtual int addReminder(const CalScheduleReminder& reminder);
+
+       /**
+        * @brief Remove reminder by index.
+        *
+        * @param[in]  nth        reminder index
+        */
        virtual void removeReminder(const int nth);
 
-       // repeat
+       /**
+        * @brief Check whether event has repeat rules.
+        *
+        * @return true if has, otherwise false.
+        *
+        */
        virtual const bool hasRepeat() const;
+
+       /**
+        * @brief Get event repeat rule.
+        *
+        * @return event repeat rule.
+        *
+        */
        virtual const CalScheduleRepeat& getRepeat() const;
+
+       /**
+        * @brief Set repeat rule to event.
+        *
+        * @param repeat       event repeat rule
+        *
+        */
        virtual void setRepeat(const CalScheduleRepeat& repeat);
 
+       /**
+        * @brief Initialization.
+        *
+        * @param[in] tzid        time zone
+        * @param[in] startTime   event start time
+        *
+        */
        virtual void initialize(const char* tzid, const CalDateTime& startTime);
 
-       bool isException() const {return getOriginalEventId() >= 0;}
+       /**
+        * @brief Check whether this instance is exception.
+        *
+        * @return true if exception, otherwise false.
+        *
+        */
+       bool isException() const { return getOriginalEventId() >= 0; }
+
+       /**
+        * @brief Check whether event is all day.
+        *
+        * @return true if all day, otherwise false.
+        *
+        */
        bool isAllDay() const;
 
-       // make
+       /**
+        * @brief Create new event instance.
+        *
+        * @param isAllDay         all day event flag.
+        *
+        * @return event instance.
+        *
+        */
        static std::shared_ptr<CalSchedule> makeDefaultSchedule(bool isAllDay = false);
+
+       /**
+        * @brief Create new event instance.
+        *
+        * @param[in] date       start date
+        *
+        * @return event instance.
+        *
+        */
        static std::shared_ptr<CalSchedule> makeDefaultSchedule(const CalDate& date);
+
+       /**
+        * @brief Create new event instance.
+        *
+        * @param[in] startTime       start date/time
+        * @param[in] endTime         end date/time
+        *
+        * @return event instance.
+        *
+        */
        static std::shared_ptr<CalSchedule> makeDefaultSchedule(const CalDateTime& startTime, const CalDateTime& endTime);
+
+       /**
+        * @brief Create new event instance.
+        *
+        * @param[in] startTime       start date/time
+        *
+        * @return event instance.
+        *
+        */
        static std::shared_ptr<CalSchedule> makeDefaultSchedule(const CalDateTime& startTime);
 
 protected:
+       CalSchedule();
+       CalSchedule(calendar_record_h record);
+       virtual ~CalSchedule();
+
+       CalSchedule(const CalSchedule&);
+       const CalSchedule& operator=(const CalSchedule&);
+
        calendar_record_h getRecord() const;
        static calendar_time_s getCaltime(const CalDateTime& startTime);
        int getOriginalEventId() const;
@@ -113,7 +426,6 @@ protected:
        void checkInsertForSync() const;
        void checkUpdateForSync() const;
 
-protected:
        virtual unsigned int getIndexProperty(void) const  = 0;
        virtual unsigned int getStartProperty(void) const = 0;
        virtual unsigned int getEndProperty(void) const = 0;
@@ -130,10 +442,11 @@ protected:
        virtual unsigned int getRecurranceIdProperty() const = 0;
        virtual unsigned int getUidProperty() const = 0;
        virtual unsigned int getSyncData2Property() const = 0;
-
-protected:
        virtual char* getExceptionString() const;
 
+       calendar_record_h __record;
+       Type __type;
+
 private:
        static std::shared_ptr<CalSchedule> __createDefaultSchedule();
        void __getFromToString(const char* timezone, const CalDateTime& start, const CalDateTime& end, std::string& text) const;
@@ -147,15 +460,11 @@ private:
        void __getStart(CalDateTime& startTime) const;
        void __getEnd(CalDateTime& endTime, bool isAdjustive = false) const;
        void __removeDuplicateReminder(void) const;
-protected:
-       calendar_record_h __record;
-       Type __type;
 
-private:
        char* __trimedSummary;
        char* __trimedLocation;
 
-friend class CalDataManager;
+       friend class CalDataManager;
 };
 
 #endif /* _CAL_SCHEDULE_H_ */