Merge pull request magento#1028 from magento-doc/MAGEDOC-1720-Sales

Magedoc 1720 sales

app/code/Magento/Sales/Api/CreditmemoCommentRepositoryInterface.php

@@ -5,37 +5,46 @@
 namespace Magento\Sales\Api;
 
 /**
- * Interface RepositoryInterface
+ * Credit memo comment repository interface.
+ *
+ * After a customer places and pays for an order and an invoice has been issued, the merchant can create a credit memo
+ * to refund all or part of the amount paid for any returned or undelivered items. The memo restores funds to the
+ * customer account so that the customer can make future purchases. A credit memo usually includes comments that detail
+ * why the credit memo amount was credited to the customer.
  */
 interface CreditmemoCommentRepositoryInterface
 {
     /**
-     * Load entity
+     * Loads a specified credit memo comment.
      *
-     * @param int $id
-     * @return \Magento\Sales\Api\Data\CreditmemoCommentInterface
+     * @param int $id The credit memo comment ID.
+     * @return \Magento\Sales\Api\Data\CreditmemoCommentInterface Credit memo comment interface.
      */
     public function get($id);
 
     /**
-     * @param \Magento\Framework\Api\SearchCriteria $criteria
-     * @return \Magento\Sales\Api\Data\CreditmemoCommentSearchResultInterface
+     * Lists credit memo comments that match specified search criteria.
+     *
+     * Returns a credit memo comment search results interface.
+     *
+     * @param \Magento\Framework\Api\SearchCriteria $criteria The search criteria.
+     * @return \Magento\Sales\Api\Data\CreditmemoCommentSearchResultInterface Credit memo comment search results interface.
      */
     public function getList(\Magento\Framework\Api\SearchCriteria $criteria);
 
     /**
-     * Delete entity
+     * Deletes a specified credit memo comment.
      *
-     * @param \Magento\Sales\Api\Data\CreditmemoCommentInterface $entity
+     * @param \Magento\Sales\Api\Data\CreditmemoCommentInterface $entity The credit memo comment.
      * @return bool
      */
     public function delete(\Magento\Sales\Api\Data\CreditmemoCommentInterface $entity);
 
     /**
-     * Perform persist operations for one entity
+     * Performs persist operations for a specified entity.
      *
-     * @param \Magento\Sales\Api\Data\CreditmemoCommentInterface $entity
-     * @return \Magento\Sales\Api\Data\CreditmemoCommentInterface
+     * @param \Magento\Sales\Api\Data\CreditmemoCommentInterface $entity The credit memo comment.
+     * @return \Magento\Sales\Api\Data\CreditmemoCommentInterface Credit memo comment interface.
      */
     public function save(\Magento\Sales\Api\Data\CreditmemoCommentInterface $entity);
 }

app/code/Magento/Sales/Api/CreditmemoItemRepositoryInterface.php

@@ -5,37 +5,44 @@
 namespace Magento\Sales\Api;
 
 /**
- * Interface RepositoryInterface
+ * Credit memo item repository interface.
+ *
+ * After a customer places and pays for an order and an invoice has been issued, the merchant can create a credit memo
+ * to refund all or part of the amount paid for any returned or undelivered items. The memo restores funds to the
+ * customer account so that the customer can make future purchases. A credit memo item is an invoiced item for which
+ * a merchant creates a credit memo.
  */
 interface CreditmemoItemRepositoryInterface
 {
     /**
-     * Load entity
+     * Loads a specified credit memo item.
      *
-     * @param int $id
-     * @return \Magento\Sales\Api\Data\CreditmemoItemInterface
+     * @param int $id The credit memo item ID.
+     * @return \Magento\Sales\Api\Data\CreditmemoItemInterface Credit memo item interface.
      */
     public function get($id);
 
     /**
-     * @param \Magento\Framework\Api\SearchCriteria $criteria
-     * @return \Magento\Sales\Api\Data\CreditmemoItemSearchResultInterface
+     * Lists credit memo items that match specified search criteria.
+     *
+     * @param \Magento\Framework\Api\SearchCriteria $criteria The search criteria.
+     * @return \Magento\Sales\Api\Data\CreditmemoItemSearchResultInterface Credit memo item search results interface.
      */
     public function getList(\Magento\Framework\Api\SearchCriteria $criteria);
 
     /**
-     * Delete entity
+     * Deletes a specified credit memo item.
      *
-     * @param \Magento\Sales\Api\Data\CreditmemoInterface $entity
+     * @param \Magento\Sales\Api\Data\CreditmemoInterface $entity The credit memo item.
      * @return bool
      */
     public function delete(\Magento\Sales\Api\Data\CreditmemoInterface $entity);
 
     /**
-     * Perform persist operations for one entity
+     * Performs persist operations for a specified credit memo item.
      *
-     * @param \Magento\Sales\Api\Data\CreditmemoInterface $entity
-     * @return \Magento\Sales\Api\Data\CreditmemoInterface
+     * @param \Magento\Sales\Api\Data\CreditmemoInterface $entity The credit memo item.
+     * @return \Magento\Sales\Api\Data\CreditmemoInterface Credit memo interface.
      */
     public function save(\Magento\Sales\Api\Data\CreditmemoInterface $entity);
 }

app/code/Magento/Sales/Api/CreditmemoManagementInterface.php

@@ -5,29 +5,34 @@
 namespace Magento\Sales\Api;
 
 /**
- * Interface CreditmemoAddCommentInterface
+ * Credit memo add comment interface.
+ *
+ * After a customer places and pays for an order and an invoice has been issued, the merchant can create a credit memo
+ * to refund all or part of the amount paid for any returned or undelivered items. The memo restores funds to the
+ * customer account so that the customer can make future purchases.
  */
 interface CreditmemoManagementInterface
 {
     /**
-     * Cancel an existing creditimemo
+     * Cancels a specified credit memo.
      *
-     * @param int $id
+     * @param int $id The credit memo ID.
      * @return bool
      */
     public function cancel($id);
 
     /**
-     * Returns list of comments attached to creditmemo
-     * @param int $id
-     * @return \Magento\Sales\Api\Data\CreditmemoCommentSearchResultInterface
+     * Lists comments for a specified credit memo.
+     *
+     * @param int $id The credit memo ID.
+     * @return \Magento\Sales\Api\Data\CreditmemoCommentSearchResultInterface Credit memo comment search results interface.
      */
     public function getCommentsList($id);
 
     /**
-     * Notify user
+     * Emails a user a specified credit memo.
      *
-     * @param int $id
+     * @param int $id The credit memo ID.
      * @return bool
      */
     public function notify($id);

app/code/Magento/Sales/Api/CreditmemoRepositoryInterface.php

@@ -5,37 +5,43 @@
 namespace Magento\Sales\Api;
 
 /**
- * Interface RepositoryInterface
+ * Credit memo repository interface.
+ *
+ * After a customer places and pays for an order and an invoice has been issued, the merchant can create a credit memo
+ * to refund all or part of the amount paid for any returned or undelivered items. The memo restores funds to the
+ * customer account so that the customer can make future purchases.
  */
 interface CreditmemoRepositoryInterface
 {
     /**
-     * @param \Magento\Framework\Api\SearchCriteria $criteria
-     * @return \Magento\Sales\Api\Data\CreditmemoSearchResultInterface
+     * Lists credit memos that match specified search criteria.
+     *
+     * @param \Magento\Framework\Api\SearchCriteria $criteria The search criteria.
+     * @return \Magento\Sales\Api\Data\CreditmemoSearchResultInterface Credit memo search result interface.
      */
     public function getList(\Magento\Framework\Api\SearchCriteria $criteria);
 
     /**
-     * Load entity
+     * Loads a specified credit memo.
      *
-     * @param int $id
-     * @return \Magento\Sales\Api\Data\CreditmemoInterface
+     * @param int $id The credit memo ID.
+     * @return \Magento\Sales\Api\Data\CreditmemoInterface Credit memo interface.
      */
     public function get($id);
 
     /**
-     * Delete entity
+     * Deletes a specified credit memo.
      *
-     * @param \Magento\Sales\Api\Data\CreditmemoInterface $entity
+     * @param \Magento\Sales\Api\Data\CreditmemoInterface $entity The credit memo.
      * @return bool
      */
     public function delete(\Magento\Sales\Api\Data\CreditmemoInterface $entity);
 
     /**
-     * Perform persist operations for one entity
+     * Performs persist operations for a specified credit memo.
      *
-     * @param \Magento\Sales\Api\Data\CreditmemoInterface $entity
-     * @return \Magento\Sales\Api\Data\CreditmemoInterface
+     * @param \Magento\Sales\Api\Data\CreditmemoInterface $entity The credit memo.
+     * @return \Magento\Sales\Api\Data\CreditmemoInterface Credit memo interface.
      */
     public function save(\Magento\Sales\Api\Data\CreditmemoInterface $entity);
 }

app/code/Magento/Sales/Api/Data/CreditmemoCommentInterface.php

@@ -5,59 +5,82 @@
 namespace Magento\Sales\Api\Data;
 
 /**
- * Interface CreditmemoCommentInterface
+ * Credit memo comment interface.
+ *
+ * After a customer places and pays for an order and an invoice has been issued, the merchant can create a credit memo
+ * to refund all or part of the amount paid for any returned or undelivered items. The memo restores funds to the
+ * customer account so that the customer can make future purchases. A credit memo usually includes comments that detail
+ * why the credit memo amount was credited to the customer.
  */
 interface CreditmemoCommentInterface extends \Magento\Framework\Api\ExtensibleDataInterface
 {
     /**#@+
-     * Constants for keys of data array. Identical to the name of the getter in snake case
+     * Constants for keys of data array. Identical to the name of the getter in snake case.
+     */
+    /*
+     * Entity ID.
      */
     const ENTITY_ID = 'entity_id';
+    /*
+     * Parent ID.
+     */
     const PARENT_ID = 'parent_id';
+    /*
+     * Is-customer-notified flag.
+     */
     const IS_CUSTOMER_NOTIFIED = 'is_customer_notified';
+    /*
+     * Is-visible-on-storefront flag.
+     */
     const IS_VISIBLE_ON_FRONT = 'is_visible_on_front';
+    /*
+     * Comment.
+     */
     const COMMENT = 'comment';
+    /*
+     * Created-at timestamp.
+     */
     const CREATED_AT = 'created_at';
 
     /**
-     * Returns comment
+     * Gets the credit memo comment.
      *
-     * @return string
+     * @return string Comment.
      */
     public function getComment();
 
     /**
-     * Returns created_at
+     * Gets the credit memo created-at timestamp.
      *
-     * @return string
+     * @return string Created-at timestamp.
      */
     public function getCreatedAt();
 
     /**
-     * Returns entity_id
+     * Gets the credit memo ID.
      *
-     * @return int
+     * @return int Credit memo ID.
      */
     public function getEntityId();
 
     /**
-     * Returns is_customer_notified
+     * Gets the is-customer-notified flag value for the credit memo.
      *
-     * @return int
+     * @return int Is-customer-notified flag value.
      */
     public function getIsCustomerNotified();
 
     /**
-     * Returns is_visible_on_front
+     * Gets the is-visible-on-storefront flag value for the credit memo.
      *
-     * @return int
+     * @return int Is-visible-on-storefront flag value.
      */
     public function getIsVisibleOnFront();
 
     /**
-     * Returns parent_id
+     * Gets the parent ID for the credit memo.
      *
-     * @return int
+     * @return int Parent ID.
      */
     public function getParentId();
 }

app/code/Magento/Sales/Api/Data/CreditmemoCommentSearchResultInterface.php

@@ -5,14 +5,19 @@
 namespace Magento\Sales\Api\Data;
 
 /**
- * Interface CreditmemoCommentSearchResultInterface
+ * Credit memo comment search result interface.
+ *
+ * After a customer places and pays for an order and an invoice has been issued, the merchant can create a credit memo
+ * to refund all or part of the amount paid for any returned or undelivered items. The memo restores funds to the
+ * customer account so that the customer can make future purchases. A credit memo usually includes comments that detail
+ * why the credit memo amount was credited to the customer.
  */
 interface CreditmemoCommentSearchResultInterface extends \Magento\Framework\Api\SearchResultsInterface
 {
     /**
-     * Get collection items
+     * Gets collection items.
      *
-     * @return \Magento\Sales\Api\Data\CreditmemoCommentInterface[]
+     * @return \Magento\Sales\Api\Data\CreditmemoCommentInterface[] Array of collection items.
      */
     public function getItems();
 }