docs: Strengthen docs for Copy&Paste and Drag&Drop

Including Eina.Content

And a typo/bugfix in ecore_evas_x.

Differential Revision: https://phab.enlightenment.org/D11204

7 files changed, 163 insertions, 99 deletions

diff --git a/src/lib/ecore_evas/Ecore_Evas.h b/src/lib/ecore_evas/Ecore_Evas.h
index ddc3622741..713ad9748f 100644
--- a/src/lib/ecore_evas/Ecore_Evas.h
+++ b/src/lib/ecore_evas/Ecore_Evas.h
@@ -3695,8 +3695,6 @@ typedef void (*Ecore_Evas_Selection_Changed_Cb)(Ecore_Evas *ee, unsigned int sea
  * Only one such callback can exist for each Ecore_Evas. Calling this method multiple
  * times overwrites previous functions. Use a NULL @p func to stop being notified.
  *
- * You will not be notified about selection changes caused by yourself. (TODO: bu5hm4n?)
- *
  * @warning If and when this function is called depends on the underlying
  * windowing system.
  */
diff --git a/src/lib/eina/eina_abstract_content.h b/src/lib/eina/eina_abstract_content.h
index 1436543f4e..32d3cc2533 100644
--- a/src/lib/eina/eina_abstract_content.h
+++ b/src/lib/eina/eina_abstract_content.h
@@ -4,22 +4,22 @@
 
 /**
  * @typedef Eina_Content
- * Defines a abstract content segment
+ * Container for any type of content.
  *
- * Each Abstract content contains out of a Eina_Slice of memory. And a type.
- * The type are IANA meme types.
+ * Each Eina_Content is made of an Eina_Slice of memory and an IANA MIME type:
+ * https://www.iana.org/assignments/media-types/media-types.xhtml
  *
- * @note if the type is a text-style type, the last byte of the slice must be \0
+ * @note if the type is a text-style type, the last byte of the slice must be \0.
  *
  * @since 1.24
  */
 typedef struct _Eina_Content Eina_Content;
 
 /**
- * @typedef Eina_Content_Convertion_Callback
+ * @typedef Eina_Content_Conversion_Callback
  *
- * Callback called when convertion from one type to another type is requested.
- * The from and to type is specified when the callback is registered.
+ * Method called when conversion from one type to another is requested.
+ * The from and to types are specified when the callback is registered.
  * The to type is also passed in the callback here.
  * The type of the from pointer does not need to be checked.
  */
@@ -38,7 +38,7 @@ EAPI const char* eina_content_as_file(Eina_Content *content);
 /**
  * Convert the content of the object to another type.
  *
- * In case the convertion cannot be performaned, NULL is returned.
+ * In case the conversion cannot be performed, NULL is returned.
  *
  * @param[in] content The content to convert.
  * @param[in] new_type The new type the returned content will have.
@@ -57,19 +57,19 @@ EAPI Eina_Content* eina_content_convert(Eina_Content *content, const char *new_t
 EAPI const char* eina_content_type_get(Eina_Content *content);
 
 /**
- * Get the type of the passed content.
+ * Get the Eina_Slice of the passed content.
  *
- * @param[in] content The content to fetch the type from.
+ * @param[in] content The content to fetch the data from.
  *
- * @return The path to the file. Do not free this.
+ * @return An Eina_Slice containing the data. Do not free.
  */
 EAPI const Eina_Slice eina_content_data_get(Eina_Content *content);
 
 /**
- * Create a new content object, with the slice of data with a specific type.
+ * Create a new content object, with the provided data and type.
  *
- * @param[in] data A slice of memory, the memory is duplicated.
- * @param[in] type The type of memory.
+ * @param[in] data A slice of memory. The memory is copied.
+ * @param[in] type The type this data represents.
  *
  * @return The new content object. The caller owns this object.
  */
@@ -85,62 +85,62 @@ EAPI void eina_content_free(Eina_Content *content);
 /**
  * Register a new conversion callback.
  *
- * @param[in] from The tyoe you convert from.
- * @param[in] in The type you convert to.
+ * @param[in] from The type to convert from.
+ * @param[in] to The type to convert to.
  *
- * @return True on success false otherwise.
+ * @return True if the callback was successfully registered.
  */
 EAPI Eina_Bool eina_content_converter_conversion_register(const char *from, const char *to, Eina_Content_Conversion_Callback convertion);
 
 /**
- * Check if a specific convertion can be performanced.
+ * Check if a specific conversion can be performed.
  *
- * A convertion can only be performed if a callback is registered.
+ * A conversion can only be performed if a callback is registered.
  *
- * @param[in] from The type you convert from.
- * @param[in] in The type you convert to.
+ * @param[in] from The type to convert from.
+ * @param[in] to The type to convert to.
  *
- * @return True if it can be performed, false if not.
+ * @return True if the conversion can be performed.
  */
 EAPI Eina_Bool eina_content_converter_convert_can(const char *from, const char *to);
 
 /**
- * Returns a iterator that can be used to find all the possible types that can be converted to.
+ * Returns an iterator containing all the target types that the provided source type can be converted to.
  *
- * @param[in] form The type you convert from
+ * @param[in] from The type to convert from.
  *
- * @return A Iterator, containing strings, free this via eina_iterator_free.
+ * @return An Iterator containing MIME type strings. Free this via eina_iterator_free.
  */
 EAPI Eina_Iterator* eina_content_converter_possible_conversions(const char *from);
 
 EAPI extern const Eina_Value_Type *EINA_VALUE_TYPE_CONTENT;
 
 /**
- * Convert the Eina_Content object to a Eina_Value.
+ * Convert the Eina_Content object to an Eina_Value.
  *
- * @param[in] content The Eina_Content struct that will be converted to a Eina_Value
+ * @param[in] content The Eina_Content struct that will be converted to an Eina_Value.
  *
- * @return A Eina_Value that is allocated, you need to free it.
+ * @return An newly-allocated Eina_Value. Caller owns it.
  */
 EAPI Eina_Value* eina_value_content_new(Eina_Content *content);
 
 /**
- * Convert the Eina_Content object to a Eina_Value.
+ * Creates an Eina_Value from an Eina_Content.
  *
- * @param[in] content The Eina_Content struct that will be converted to a Eina_Value
+ * @param[in] content The Eina_Content struct that will be converted to an Eina_Value.
  *
- * @return A Eina_Value with type EINA_VALUE_TYPE_CONTENT
+ * @return An Eina_Value with type EINA_VALUE_TYPE_CONTENT.
  */
 EAPI Eina_Value eina_value_content_init(Eina_Content *content);
 
 /**
- * Get the content from the Eina_Value
+ * Gets the content from the Eina_Value.
  *
- * If the value is not of the type EINA_VALUE_TYPE_CONTENT, NULL will be returned and a error will be printed.
+ * If the value is not of the type EINA_VALUE_TYPE_CONTENT, NULL will be returned and an error will be printed.
  *
  * @param[in] value The value to get the content from
  *
- * @return A allocated Eina_Content, you need to free it.
+ * @return A newly-allocated Eina_Content. Caller owns it.
  */
 EAPI Eina_Content* eina_value_to_content(const Eina_Value *value);
 
diff --git a/src/lib/elementary/efl_ui_dnd.eo b/src/lib/elementary/efl_ui_dnd.eo
index 8ef19110d5..24ace0617c 100644
--- a/src/lib/elementary/efl_ui_dnd.eo
+++ b/src/lib/elementary/efl_ui_dnd.eo
@@ -1,63 +1,89 @@
 import eina_types;
 
 struct @beta Efl.Ui.Drop_Event {
-   [[Event struct that contains information about what is avaiable at which position, in which seat]]
-   position : Eina.Position2D; [[The position of the Drop event]]
-   seat : uint; [[In which seat it is happening]]
-   available_types : accessor<string>; [[which types are avaiable, you should use one of these for a call to @Efl.Ui.Dnd.drop_data_get ]]
+   [[Information sent along Drag & Drop events.]]
+   position : Eina.Position2D; [[The position where the drop event occurred, in window coordinates.]]
+   seat : uint; [[Which seat triggered the event.]]
+   available_types : accessor<string>; [[Types with automatic conversion available. Use one of them in the call to
+                                         @Efl.Ui.Dnd.drop_data_get.
+
+                                         Types are IANA MIME types:
+                                         https://www.iana.org/assignments/media-types/media-types.xhtml
+                                       ]]
 }
 
 struct @beta Efl.Ui.Drop_Dropped_Event {
-   dnd : Efl.Ui.Drop_Event; [[The overall information]]
-   action : string; [[The action the client should take]]
+   [[Information sent along Drop events.]]
+   dnd : Efl.Ui.Drop_Event; [[Common information.]]
+   action : string; [[Requested action to perform upon reception of this data.]]
 }
 
 struct @beta Efl.Ui.Drag_Started_Event {
-   seat : uint;
+   [[Information sent along @Efl.Ui.Drag_Started_Event events.]]
+   seat : uint; [[Which seat triggered the event.]]
 }
 
 struct @beta Efl.Ui.Drag_Finished_Event {
-   seat : uint;
-   accepted : bool;
+   [[Information sent along @Efl.Ui.Drag_Finished_Event events.]]
+   seat : uint; [[Which seat triggered the event.]]
+   accepted : bool; [[$true if the operation completed with a Drop, or $false if it was cancelled.]]
 }
 
 mixin @beta Efl.Ui.Dnd requires Efl.Object {
+   [[This mixin provides the ability to interact with the system's Drag & Drop facilities.
+
+     Applications starting a Drag & Drop operation operation are said to perform a "Drag" and use
+     the methods prefixed "drag_".
+     On the other hand, applications receiving dragged content are said to perform a "Drop" operation and use
+     the methods prefixed "drop_".
+   ]]
    methods {
       drag_start {
-         [[Start a drag from this client.
+         [[Starts a drag from this client.
 
-           @[Efl.Ui.Dnd.drag,started] will be emitted each time a successfull drag will be started.
-           @[Efl.Ui.Dnd.drag,finished] will be emitted every time a drag is finished.
+           @[Efl.Ui.Dnd.drag,started] is emitted each time a successful drag is started.
+           @[Efl.Ui.Dnd.drag,finished] is emitted every time a drag is finished.
          ]]
          params {
-            content : Eina.Content @by_ref; [[The content you want to provide via dnd]]
-            @in action: string; [[Action when data is transferred]]
-            @in seat: uint; [[Specified seat for multiple seats case.]]
+            content : Eina.Content @by_ref; [[The content being dragged.]]
+            @in action: string; [[Requested action to perform by the receiver once content is transferred.]]
+            @in seat: uint; [[Seat starting the drag operation. When in doubt use 0.]]
          }
-         return : Efl.Content; [[A UI element where you can just set your visual representation into]]
+         return : Efl.Content; [[An Efl.Ui element which you can use to render a visual representation
+                                 of the content being dragged (like a thumbnail, for example).
+                                 Use @Efl.Content.content.set on it to do so.]]
       }
       drag_cancel {
-         [[Cancel the on-going drag]]
+         [[Cancels an on-going drag operation.]]
          params {
-            @in seat: uint; [[Specified seat for multiple seats case.]]
+            @in seat: uint; [[Seat that started the drag operation. When in doubt use 0.]]
          }
       }
       drop_data_get {
-         [[Get the data from the object that has selection]]
+         [[Retrieves the dropped data.]]
          params {
-           seat : uint;  [[Specified seat for multiple seats case.]]
-           acceptable_types : iterator<string>; [[The types that are acceptable for you]]
+            @in seat: uint; [[Seat that started the drag operation. When in doubt use 0.]]
+            @in acceptable_types : iterator<string>; [[List of strings describing the type of content the application
+                                                       can accept. Types are IANA MIME types:
+                                                       https://www.iana.org/assignments/media-types/media-types.xhtml.]]
          }
-         return : future<Eina.Content> @move; [[fullfilled when the content is transmitted, and ready to use]]
+         return : future<Eina.Content> @move; [[This future is fulfilled when the content is received (asynchronously)
+                                                and ready to use.
+                                                The Eina.Content specifies the type of the data.
+                                                If no matching type was found it returns an error.
+                                              ]]
       }
    }
    events {
-      drop,entered : Efl.Ui.Drop_Event;
-      drop,left : Efl.Ui.Drop_Event;
-      drop,position,changed : Efl.Ui.Drop_Event;
-      drop,dropped : Efl.Ui.Drop_Dropped_Event;
-      drag,started : Efl.Ui.Drag_Started_Event;
-      drag,finished : Efl.Ui.Drag_Finished_Event;
+      drop,entered : Efl.Ui.Drop_Event; [[Dragged content entered the window. Its type can already be checked with
+                                          @.drop_data_get to react before it is dropped, for example.]]
+      drop,left : Efl.Ui.Drop_Event;    [[Dragged content left the window.]]
+      drop,position,changed : Efl.Ui.Drop_Event; [[Dragged content moved over the window. Its type can already be
+                                                   checked with @.drop_data_get to react before it is dropped,
+                                                   for example.]]
+      drop,dropped : Efl.Ui.Drop_Dropped_Event;  [[Dragged content was dropped over the window.]]
+      drag,started : Efl.Ui.Drag_Started_Event;  [[A Drag operation started.]]
+      drag,finished : Efl.Ui.Drag_Finished_Event;[[A Drag operation finished.]]
    }
    implements {
       Efl.Object.constructor;
diff --git a/src/lib/elementary/efl_ui_selection.eo b/src/lib/elementary/efl_ui_selection.eo
index 492e60e117..7e0814d348 100644
--- a/src/lib/elementary/efl_ui_selection.eo
+++ b/src/lib/elementary/efl_ui_selection.eo
@@ -1,49 +1,76 @@
 import eina_types;
 
-enum @beta Efl.Ui.Cnp_Buffer{
-   selection = 0,
-   copy_and_paste = 1,
+enum @beta Efl.Ui.Cnp_Buffer {
+   [[System buffer to use in Copy & Paste operations.]]
+   selection = 0,      [[Buffer typically used when the user selects (highlights) some text without explicitly
+                         requesting to copy it.]]
+   copy_and_paste = 1, [[Buffer used when the user requests that the current selection is copied (using
+                         Ctrl+C, for example).]]
 }
 
 struct @beta Efl.Ui.Wm_Selection_Changed {
-   buffer : Efl.Ui.Cnp_Buffer;
-   caused_by : Efl.Ui.Selection;
-   seat : uint;
+   [[Information sent along the @[Efl.Ui.Selection.wm_selection,changed] event.]]
+   buffer : Efl.Ui.Cnp_Buffer; [[The system buffer that has changed.]]
+   caused_by : Efl.Ui.Selection; [[The EFL widget that triggered the change. $NULL if it is not an EFL widget.]]
+   seat : uint; [[The seat that triggered the change.]]
 }
 
 mixin @beta Efl.Ui.Selection requires Efl.Object {
+  [[This mixin provides the ability to interact with the system's Copy & Paste facilities.
+  ]]
   methods {
     selection_set {
-      [[Set the selection data to the object]]
+      [[Sets the current selection.
+
+        This sends the selected data to the system's specified buffer, making it available to other
+        applications for "pasting" it.
+
+        This is typically used when the user requests a "copy" operation.
+      ]]
       params {
-        buffer : Efl.Ui.Cnp_Buffer;
-        content : Eina.Content @by_ref;
-        seat : uint;
+        buffer : Efl.Ui.Cnp_Buffer; [[System buffer to use.]]
+        content : Eina.Content @by_ref; [[Data to copy.]]
+        seat : uint; [[Seat the data comes from. Use 0 when in doubt.]]
       }
     }
     selection_clear {
-      [[Clear the selection data from the object]]
+      [[Clears the current selection.
+
+        No data will be available to other applications to paste (until something else is selected).
+      ]]
       params {
-        buffer : Efl.Ui.Cnp_Buffer;
-        seat : uint;
+        buffer : Efl.Ui.Cnp_Buffer; [[System buffer to clear.]]
+        seat : uint; [[Seat to clear. Use 0 when in doubt.]]
       }
     }
     selection_get {
-      [[Get the data from the object that has selection]]
+      [[Retrieves the data currently held in the specified buffer.
+
+        This is typically used when the user requests a "paste" operation.
+
+        This method is time consuming (since data can potentially be provided by another application), therefore,
+        it is recommended to verify the existence of a selection using @.has_selection before calling it.
+      ]]
       params {
-        buffer : Efl.Ui.Cnp_Buffer;
-        seat : uint;
-        acceptable_types : iterator<string>;
+        buffer : Efl.Ui.Cnp_Buffer; [[System buffer to use.]]
+        seat : uint; [[Seat where the data should be pasted. Use 0 when in doubt.]]
+        acceptable_types : iterator<string>; [[List of accepted IANA MIME types:
+                                               https://www.iana.org/assignments/media-types/media-types.xhtml
+                                               If automatic conversion cannot be provided to any of the accepted
+                                               types, an error will be returned.
+                                             ]]
       }
-      return : future<Eina.Content> @move;
+      return : future<Eina.Content> @move; [[A future that will be resolved to the requested content, or to an
+                                             error if type conversion is not available or the requested buffer
+                                             is empty.]]
     }
     has_selection {
-      [[Determine whether the selection data has owner]]
+      [[Checks if the specified system buffer has content.]]
       params {
-        buffer : Efl.Ui.Cnp_Buffer;
-        seat : uint;
+        buffer : Efl.Ui.Cnp_Buffer; [[System buffer to query.]]
+        seat : uint; [[Seat to query. Use 0 when in doubt.]]
       }
-      return : bool; [[$true if there is a available selection, $false if not]]
+      return : bool; [[$true if there is data available in the requested buffer.]]
     }
   }
   implements {
@@ -52,6 +79,7 @@ mixin @beta Efl.Ui.Selection requires Efl.Object {
     Efl.Object.finalize;
   }
   events {
-    wm_selection,changed : Efl.Ui.Wm_Selection_Changed;
+    wm_selection,changed : Efl.Ui.Wm_Selection_Changed; [[Event emitted when the content of one of the system's
+                                                          buffers changes.]]
   }
 }
diff --git a/src/lib/elementary/efl_ui_textbox.eo b/src/lib/elementary/efl_ui_textbox.eo
index ff0898b6fc..2605c477a3 100644
--- a/src/lib/elementary/efl_ui_textbox.eo
+++ b/src/lib/elementary/efl_ui_textbox.eo
@@ -1,8 +1,13 @@
-enum Efl.Ui.Textbox_Cnp_Content {
-   Nothing = 0, [[You can paste or drop nothing]]
-   Text = 1, [[You can paste normal Text]]
-   Markup = 3, [[You can paste Markup (Normal text is also just markup)]]
-   Image = 4, [[You can paste Images]]
+enum @beta Efl.Ui.Textbox_Cnp_Content {
+   [[What kind of content can be pasted into this widget using Copy & Paste or Drag & Drop functionality.
+
+     Multiple options can be OR-ed together.
+   ]]
+   Nothing = 0, [[Nothing can be pasted or dropped into this widget.]]
+   Text = 1,    [[Plain text can be pasted or dropped into this widget.]]
+   Markup = 3,  [[Markup text can be pasted or dropped into this widget
+                  (This includes Plain text).]]
+   Image = 4,   [[Images can be pasted or dropped into this widget.]]
 }
 
 class @beta Efl.Ui.Textbox extends Efl.Ui.Layout_Base implements Efl.Input.Clickable,
@@ -39,18 +44,16 @@ class @beta Efl.Ui.Textbox extends Efl.Ui.Layout_Base implements Efl.Input.Click
          }
       }
       @property cnp_dnd_mode @beta {
-         [[Control pasting of text and images for the widget.
-
-           Normally the entry allows both text and images to be pasted.
+         [[Controls the type of content which can be pasted into the widget.
 
-           Note: This only changes the behaviour of text.
+           By default, both text and images are allowed..
          ]]
          set {
          }
          get {
          }
          values {
-            allowed_formats : Efl.Ui.Textbox_Cnp_Content; [[Format for cnp]]
+            allowed_formats : Efl.Ui.Textbox_Cnp_Content; [[Allowed content types.]]
          }
       }
       @property selection_handles_enabled {
diff --git a/src/lib/eo/eina_types.eot b/src/lib/eo/eina_types.eot
index 106aa0885d..000a2567d9 100644
--- a/src/lib/eo/eina_types.eot
+++ b/src/lib/eo/eina_types.eot
@@ -60,7 +60,16 @@ struct @extern Eina.Matrix3 {
    zz: double; [[ZZ value.]]
 }
 
-struct @extern Eina.Content;
+struct @extern Eina.Content; [[
+  Container for any type of content.
+
+  Each @Eina.Content is made of an @Eina.Slice of memory and an IANA MIME type:
+  https://www.iana.org/assignments/media-types/media-types.xhtml
+
+  If the type is a text-style type, the last byte of the slice must be \0.
+
+  @since 1.24
+]]
 
 struct @extern Eina.Matrix4 {
    [[A bidimensional array of floating point values with 4 rows and 4 columns.
diff --git a/src/modules/ecore_evas/engines/x/ecore_evas_x.c b/src/modules/ecore_evas/engines/x/ecore_evas_x.c
index d689a5622c..36afeb5495 100644
--- a/src/modules/ecore_evas/engines/x/ecore_evas_x.c
+++ b/src/modules/ecore_evas/engines/x/ecore_evas_x.c
@@ -3794,7 +3794,7 @@ _search_fitting_type(Ecore_Evas *ee, Ecore_Evas_Engine_Data_X11 *edata, Ecore_Ev
              if (mime_type == acceptable_type)
                HANDLE_TYPE()
 
-             //if there is no available type yet, check if we can convert to the desiared type via this type
+             //if there is no available type yet, check if we can convert to the desired type via this type
              if (!found_conversion)
                {
                   const char *convertion_type = NULL;