update stylesheet.css, Self.h

1 files changed, 95 insertions, 58 deletions

diff --git a/meowpp/Self.h b/meowpp/Self.h
index 7de568b..aefc7a3 100644
--- a/meowpp/Self.h
+++ b/meowpp/Self.h
@@ -6,64 +6,109 @@
 namespace meow {
 
 /*!
- *@brief 具有copy on write, 且擁有比C++更靈活的reference機制
+ *@brief A little class use for packing the data part of another class.
+ *       With this technique, it can achieve Copy-On-Write(COR) mechanism at
+ *       background and have a reference mechanism which much more flexible
+ *       then the one C++ has.
  *
- *使用上就是把所有成員變數包到一個class/structure裡, 送給Self \n
- *例如以下
+ * Sample code:
  *@code{.cpp}
  * class A {
  * private:
  *   struct Myself {
  *     int data;
- *     Myself() {                               // 必要
+ *
+ *     Myself() {                               // Necessary
  *       data = 0;
  *     }
- *     Myself(Myself const& b): data(b.data) {  // 必要, copy constructor
+ *
+ *     Myself(Myself const& b): data(b.data) {  // Necessary, copy constructor
  *     }
+ *
  *     ~Myself() {
  *     }
- *     bool operator==(Myself const& b) const { // 不一定需要(有用到equal()才要)
+ *
+ *     bool operator==(Myself const& b) const { // Optional (this method will
+ *                                              // be called only if you use
+ *                                              // Self::equal() method)
  *       return (data == b.data);
  *     }
  *   };
  *
- *   Self<Myself> const self;
+ *   Self<Myself> const self;          // Here we use 'constant' data type in 
+ *                                     // order to have a coutious coding style
+ *                                     // and allow the COR mechanism to clone
+ *                                     // data only when we really want to
+ *                                     // modify them.
  * public:
- *   A(): self() { }                                // 預設呼叫Myself()
- *   A(A const& a): self(a.self, COPY_FROM) { }     // 用Myself(b)做到copyFrom
+ *   A(): self() { }                            // Default constructor
+ *
+ *   A(A const& a): self(a.self, COPY_FROM) { } // Copy constructor. You must
+ *                                              // tell me which way of
+ *                                              // duplicating should I use.
+ *                                              // It strongly recommended you
+ *                                              // use COYP_FROM for keeping the
+ *                                              // C++'s original behavior.
  *   ~A() { }
- *   void setMemeber(int k) {
- *     self()->data = k;  // self()->?? 可以有write權限
- *   }
+ *
  *   int getMemember(int wh) const {
- *     return self->data; // self->?? 只有const
+ *     return self->data;   // Use 'operator->()' to get the pointer of the data
+ *                          // The pointer is constant or not will depend on
+ *                          // whether the left side variable of '->' is
+ *                          // constant or not.
+ *                          // If we just want to read the data, use
+ *                          // 'self' instead of 'self()'
  *   }
+ *   void setMemeber(int k) {
+ *     self()->data = k;    // As a result of 'self()' returning a non-constant
+ *                          // reference of itself, here we get the permission
+ *                          // for modiying data.
+ *                          // So now we can observe that if you type
+ *                          // 'Self<Myself> self' instead of the one above,
+ *                          // 'self' and 'self()' will become the same one and
+ *                          // both of them allow you using '->' for getting
+ *                          // writing permission. At the same time, the COR
+ *                          // machanism will become useless because everytime
+ *                          // you want to access the date, Self will copy the
+ *                          // data to prevent you to modify it no matter that
+ *                          // you might just want to read it.
+ *   }
+ *
  *   A referenceFrom(A const& a) {
  *     self.referenceFrom(a.self);
  *   }
+ *
  *   A copyFrom(A const& a) {
  *     self.copyFrom(a.self);
  *   }
- *   A& operator=(A const& b) { // for std::swap
+ *
+ *   A& operator=(A const& b) { // If you really like to use operator=, it
+ *                              // strongly recommended you use 'copyFrom()' for
+ *                              // keeping C++'s original behavior.
  *     copyFrom(b);
  *   }
  * };
- * @endcode
+ *@endcode
+ * Note that 'referenceFrom()' will cause the two object become the same one,
+ * Which means that if you do something like '\c a.referenceFrom(b);
+ * \c a.copyFrom(c); ', the result is that the value of \c a,b,c will all the
+ * same one.
  *
- * @author cathook
+ *@author cathook
  *
- * @warning \c Self 這個class會把\c operator= 給disable掉, 所以使用它當
- *          kernel的class預設的 \c operator= 都會無法使用
+ *@warning This class disabled the method \c operator= and copy constructor
+ *         in order to prevent upexplicit default behavior, so if you want
+ *         to have one of them (or both), you must implement yourself
  */
 template<class Data>
 class Self {
 public:
   /*!
-   * @brief 複製資料的方法
+   * @brief Kind of ways of duplicating
    */
   enum DuplicateType {
-    COPY_FROM,          //!< 跟一般的複製一樣
-    REFERENCE_FROM      //!< 參照, 執行完兩個Self會完全等效
+    COPY_FROM,          //!< Normal copy operation
+    REFERENCE_FROM      //!< By reference, much like pointer's copy operation
   };
 private:
   class Body {
@@ -123,27 +168,24 @@ private:
   }
 public:
   /*!
-   *@brief constructor, 並宣告一個實體
+   * @brief constructor with a real entity
    */
   Self(): body_(new Body()) {
   }
 
   /*!
-   * @brief connstructor, 宣告一個實體, 其中該實體的constructor用copy
-   *        constructor
+   * @brief connstructor with a real entity with it using its copy constructor
    *
    * @param [in] d Inital data
-   *
    */
   Self(Data const& d): body_(new Body(d)) {
   }
 
   /*!
-   * @brief constructor, 使用給定的Self當作init value, 並且可以指定要用
-   *         reference還是copy
+   * @brief constructor with given another Self
    *
-   * @param [in] b 給定的Self
-   * @param [in] d 指定要用copy還是reference
+   * @param [in] b Another Self object.
+   * @param [in] d To indicate type of way of duplicating
    */
   Self(Self const& b, DuplicateType d) {
     switch(d) {
@@ -160,34 +202,33 @@ public:
   //! @brief Disallow copy constructor
   Self(Self const& b);
 
-  //! @brief 解構子
+  //! @brief destructor
   ~Self() {
     clear();
   }
 
-  //! @brief 回傳指向 Data const 的指標
+  //! @brief Return the constant pointer to the data
   Data const* operator->() const {
     return body_->access();
   }
 
-  //! @brief 回傳指向 Data 的指標, 如有需要, 這邊會做資料的duplicate
+  /*! @brief Return the non-constant pointer to the data (COR's clone might
+   *         occure here.
+   */
   Data* operator->() {
     return body_->modify();
   }
 
-  //! @brief 回傳非const型態的自己
+  //! @brief Return the non-constant reference of \c *this
   Self& operator()() const {
     return *((Self*)this);
   }
 
   /*!
-   * @brief 將給定的 \c Self 的資料複製到自己這裡
+   * @brief Copy the gived \c Self to myself
    *
-   * @param [in] s 給定的\c Self
+   * @param [in] s gived \c Self
    * @return *this
-   *
-   * @note 與reference的差別是, copy之後若該給定的 \c Self 有資料修改,
-   *       this 這邊 \b 不會 被改到
    */
   Self const& copyFrom(Self const& s) {
     if (body_->access() != s.body_->access()) {
@@ -197,14 +238,10 @@ public:
   }
 
   /*!
-   * @brief 將自己reference 到給定的 \c Self
+   * @brief Reference myself from given \c Self object.
    *
-   * @param [in] s 給定的\c Self
+   * @param [in] s given \c Self
    * @return *this
-   *
-   * @note 把reference想像成指標會比較容易思考, 譬如 \c a.referenceFrom(b)
-   *       \c b.referenceFrom(c) 相當於 \b a指向b原本指的記憶體位置,
-   *       \b b指向c原本指的記憶體位置 , 之後更動c時, 只有b會被牽連
    */
   Self const& referenceFrom(Self const& s) {
     if (body_ != s.body_) {
@@ -216,10 +253,10 @@ public:
   }
 
   /*!
-   * @brief 依據給定DuplicateType選擇要呼叫copyFrom還是referenceFrom
+   * @brief call \c copyFrom() or \c referenceFrom() depend on your instruction
    *
-   * @param [in] s 給定的 \c Self
-   * @param [in] t 給定的 \c DuplicateType
+   * @param [in] s gived \c Self object
+   * @param [in] t instruction
    * @return *this
    */
   Self const& duplicateFrom(Self const& s, DuplicateType t) {
@@ -231,22 +268,23 @@ public:
   }
 
   /*!
-   * @brief 比對兩個 \c Self 是否指向同一個reference
+   * @brief Compare tht if the gived \c Self object is reference from the same
+   *        object of me
    *
-   * @param [in] s 另一個 \c Self
-   * @return \c true/false 表示是否為同一個reference
+   * @param [in] s gived \c Self object
+   * @return \c true if we are referenced to the same object.
    */
   bool same(Self const& s) const {
     return (body_ == s.body_);
   }
 
   /*!
-   * @brief 比對兩個 \c Self 的內容是否一樣
+   * @brief Compare that the data are the same.
    *
-   * @param [in] s 另一個 \c Self
-   * @return \c true/false 表示兩個內容是否一樣
+   * @param [in] s another \c Self object
+   * @return \c true if the data are same.
    *
-   * @note 需要用到 Data的equal()
+   * @note This will need the method 'Data::equal()'
    */
   bool equal(Self const& s) const {
     if (same(s) || body_->access() == s.body_->access()) return true;
@@ -254,16 +292,15 @@ public:
   }
 
   /*!
-   * @brief 以reference作為判斷依據的小於判斷
+   * @brief Order compare by reference pointer.
    *
-   * @param [in] s 另一個 \c Self
-   * @return \c true/false 表示自己是否小於另一個 \c Self
+   * @param [in] s another \c Self object
    */
   bool referenceLess(Self const& s) const {
     return (body_ < s.body_);
   }
 
-  //! @brief 將 \c operator= 給disable掉
+  //! @brief Disallow default \c 'operator='
   void operator=(Self const& a);
 };