reviewed cnp docs, added an api FIXME

SVN revision: 68482

legacy/elementary/src/lib/elm_cnp.h

@@ -1,39 +1,39 @@
 /**
  * @defgroup CopyPaste CopyPaste
  *
- * Implement the following functionality
+ * Implements the following functionality
  *    a. select, copy/cut and paste 
  *    b. clipboard
  *    c. drag and drop 
  * in order to share data across application windows.
  *
- * Contains functions to select a portion of text, stick it to a clipboard
- * and to paste the selection to an appropriate place.
+ * Contains functions to select a portion of text, send it to a buffer,
+ * and paste the selection into a target.
  *
  * @{
  */
 
 /**
  * Defines the types of selection property names.
- * Kindly refer to http://www.x.org/docs/X11/xlib.pdf
+ * @see http://www.x.org/docs/X11/xlib.pdf
  * for more details.
  */
 typedef enum
 {
-   ELM_SEL_TYPE_PRIMARY, // refers to primary text selection
-   ELM_SEL_TYPE_SECONDARY, // used when primary selection is in use.
-   ELM_SEL_TYPE_XDND, // drag and drop
-   ELM_SEL_TYPE_CLIPBOARD, // selected text 
+   ELM_SEL_TYPE_PRIMARY, /**< Primary text selection (middle mouse) */
+   ELM_SEL_TYPE_SECONDARY, /**< Used when primary selection is in use */
+   ELM_SEL_TYPE_XDND, /**< Drag 'n' Drop */
+   ELM_SEL_TYPE_CLIPBOARD, /**< Clipboard selection (ctrl+C)
 } Elm_Sel_Type;
 
 /**
- * Defines the types of target.
+ * Defines the types of content.
  */
 typedef enum
 {
-   /** Targets: for matching every atom requesting */
+   /** For matching every possible atom */
    ELM_SEL_FORMAT_TARGETS = -1,
-   /** they come from outside of elm */
+   /** Content is from outside of Elementary */
    ELM_SEL_FORMAT_NONE = 0x0,
    /** Plain unformatted text: Used for things that don't want rich markup */
    ELM_SEL_FORMAT_TEXT = 0x01,
@@ -43,7 +43,7 @@ typedef enum
    ELM_SEL_FORMAT_IMAGE = 0x04,
    /** Vcards */
    ELM_SEL_FORMAT_VCARD = 0x08,
-   /** Raw HTML-like data (ex., webkit) */
+   /** Raw HTML-like data (eg. webkit) */
    ELM_SEL_FORMAT_HTML = 0x10,
 } Elm_Sel_Format;
 
@@ -62,25 +62,26 @@ typedef struct _Elm_Selection_Data Elm_Selection_Data;
 /**
  * Callback invoked in when the selected data is 'dropped' at its destination.
  *
- * @param d Application specific data
- * @param o The evas object where selected data is 'dropped'.
- * @param data struct holding information about selected data
+ * @param data Application specific data
+ * @param obj The evas object where selected data is 'dropped'.
+ * @param ev struct holding information about selected data
+ * FIXME: this should probably be a smart callback
  */
-typedef Eina_Bool (*Elm_Drop_Cb)(void *d, Evas_Object *o, Elm_Selection_Data *data);
+typedef Eina_Bool (*Elm_Drop_Cb)(void *data, Evas_Object *obj, Elm_Selection_Data *ev);
 
 
 /**
- * @brief Set copy and paste data to a widget.
+ * @brief Set copy and paste data for a widget.
  *
  * XXX: need to be rewritten.
  * Append the given callback to the list.
  *
  * @param selection Selection type for copying and pasting
  * @param obj The source widget pointer
- * @param format Type of selection format
- * @param buf The pointer of data source
- * @param buflen The size of @c buf
- * @return If EINA_TRUE, setting data is success.
+ * @param format Selection format
+ * @param buf The data selected
+ * @param buflen The size of @p buf
+ * @return If EINA_TRUE, setting data was successful.
  *
  * @ingroup CopyPaste
  *
@@ -93,20 +94,21 @@ EAPI Eina_Bool elm_cnp_selection_set(Elm_Sel_Type selection, Evas_Object *obj,
                                      size_t buflen);
 
 /**
- * @brief Retrieve the copy and paste data from the widget.
+ * @brief Retrieve selection data from a widget.
  *
- * Gets the data from the widget which is set for copying and pasting.
- * Mainly the widget is elm_entry. If then @p datacb and @p udata can be NULL.
- * If not, @p datacb and @p udata are used for retrieving data.
+ * Gets the current selection data from a widget.
+ * The widget input here will usually be elm_entry,
+ * in which case @p datacb and @p udata can be NULL.
+ * If a different widget is passed, @p datacb and @p udata are used for retrieving data.
  *
  * @see also elm_cnp_selection_set()
  *
  * @param selection Selection type for copying and pasting
- * @param format Type of selection format
- * @param obj The source widget pointer
+ * @param format Selection format
+ * @param obj The source widget
  * @param datacb The user data callback if the target widget isn't elm_entry
  * @param udata The user data pointer for @p datacb
- * @return If EINA_TRUE, getting data is success.
+ * @return If EINA_TRUE, getting selection data was successful.
  *
  * @ingroup CopyPaste
  *
@@ -125,13 +127,13 @@ EAPI Eina_Bool elm_cnp_selection_get(Elm_Sel_Type selection,
                                      Elm_Drop_Cb datacb, void *udata);
 
 /**
- * @brief Clear the selected/copied data in the widget.
+ * @brief Clear the selection data of a widget.
  *
  * @see also elm_cnp_selection_set()
  *
- * @param obj The source widget pointer
+ * @param obj The source widget
  * @param selection Selection type for copying and pasting
- * @return If EINA_TRUE, clearing data is success.
+ * @return If EINA_TRUE, clearing data was successful.
  *
  * @ingroup CopyPaste
  *