From 539b2711c8331fb318d80a1cd93b155ac017863c Mon Sep 17 00:00:00 2001
From: Xavi Artigas <xavierartigas@yahoo.es>
Date: Tue, 2 Apr 2019 08:57:19 -0400
Subject: [PATCH] docs: Format efl_file.h

Summary:
And polish a bit.

Ref T7717

Test Plan: Only docs updated

Reviewers: zmike

Reviewed By: zmike

Subscribers: bu5hm4n, cedric, #reviewers, #committers

Tags: #efl

Maniphest Tasks: T7717

Differential Revision: https://phab.enlightenment.org/D8498
---
 src/lib/efl/interfaces/efl_file.eo  | 36 ++++++++++++++++++------------------
 src/lib/elementary/efl_ui_image.eo  |  6 +++++-
 src/lib/elementary/efl_ui_layout.eo |  4 ++++
 3 files changed, 27 insertions(+), 19 deletions(-)

diff --git a/src/lib/efl/interfaces/efl_file.eo b/src/lib/efl/interfaces/efl_file.eo
index 6711dfb..7d1ee49 100644
--- a/src/lib/efl/interfaces/efl_file.eo
+++ b/src/lib/efl/interfaces/efl_file.eo
@@ -1,5 +1,4 @@
 import eina_types;
-import efl_gfx_types;
 
 mixin Efl.File requires Efl.Object {
    [[Efl file interface
@@ -10,23 +9,21 @@ mixin Efl.File requires Efl.Object {
       @property mmap {
          set {
             [[Set the mmaped file from where an object will fetch the real
-              data (it must be an Eina_File).
+              data (it must be an @Eina.File).
 
               If mmap is set during object construction, the object will automatically
               call @.load during the finalize phase of construction.
-
-              ]]
+            ]]
 
             return: Eina.Error; [[0 on success, error code otherwise]]
          }
          get {
             [[Get the mmaped file from where an object will fetch the real
-              data (it must be an Eina_File).
-
-              ]]
+              data (it must be an @Eina.File).
+            ]]
          }
          values {
-            f: ptr(const(Eina.File)); [[The handle to an Eina_File that will be used]]
+            f: ptr(const(Eina.File)); [[The handle to the @Eina.File that will be used]]
          }
       }
       @property file {
@@ -42,7 +39,8 @@ mixin Efl.File requires Efl.Object {
          get {
             [[Retrieve the file path from where an object is to fetch the data.
 
-              You must not modify the strings on the returned pointers.]]
+              You must not modify the strings on the returned pointers.
+            ]]
          }
          values {
             file: string; [[The file path.]]
@@ -60,15 +58,16 @@ mixin Efl.File requires Efl.Object {
             [[Get the previously-set key which corresponds to the target data within a file.
 
               Some filetypes can contain multiple data streams which are indexed by
-              a key. Use this property for such cases.
+              a key. Use this property for such cases (See for example @Efl.Ui.Image or
+              @Efl.Ui.Layout).
 
-              You must not modify the strings on the returned pointers.]]
+              You must not modify the strings on the returned pointers.
+            ]]
          }
          values {
-            key: string; [[The group that the image belongs to, in case
-                                            it's an EET(including Edje case) file. This can be used
-                                            as a key inside evas image cache if this is a normal image
-                                            file not eet file.]]
+            key: string; [[The group that the data belongs to. See the class documentation
+                           for particular implementations of this interface to see how this
+                           property is used.]]
          }
       }
       @property loaded {
@@ -77,7 +76,7 @@ mixin Efl.File requires Efl.Object {
             ]]
          }
          values {
-            loaded: bool; [[True if the object is loaded, otherwise false.]]
+            loaded: bool; [[$true if the object is loaded, $false otherwise.]]
          }
       }
 
@@ -89,9 +88,10 @@ mixin Efl.File requires Efl.Object {
            open the file and call @.mmap.set on the object using the opened file handle.
 
            Calling @.load on an object which has already performed file operations based on
-           the currently set properties will have no effect.]]
+           the currently set properties will have no effect.
+         ]]
 
-           return: Eina.Error; [[0 on success, error code otherwise]]
+         return: Eina.Error; [[0 on success, error code otherwise]]
       }
 
       unload {
diff --git a/src/lib/elementary/efl_ui_image.eo b/src/lib/elementary/efl_ui_image.eo
index cae449f..5202850 100644
--- a/src/lib/elementary/efl_ui_image.eo
+++ b/src/lib/elementary/efl_ui_image.eo
@@ -23,7 +23,11 @@ class @beta Efl.Ui.Image extends Efl.Ui.Widget implements Efl.Ui.Clickable, Efl.
                  Efl.Layout.Calc,
                  Efl.Layout.Group, Efl.Layout.Signal
 {
-   [[ Efl UI image class]]
+   [[Efl UI image class
+
+     When loading images from a file, the @Efl.File.key property can be used to access different
+     streams. For example, when accessing Evas image caches.
+   ]]
    event_prefix: efl_ui_image;
    methods {
       @property scalable {
diff --git a/src/lib/elementary/efl_ui_layout.eo b/src/lib/elementary/efl_ui_layout.eo
index 8738f3d..bdc81db 100644
--- a/src/lib/elementary/efl_ui_layout.eo
+++ b/src/lib/elementary/efl_ui_layout.eo
@@ -4,6 +4,10 @@ class Efl.Ui.Layout extends Efl.Ui.Layout_Base implements Efl.File
 {
    [[Elementary layout class
 
+     When loading layouts from a file, use the @Efl.File.key property to specify
+     the group that the data belongs to, in case it's an EET file
+     (including Edje files).
+
      @since 1.22
    ]]
    data: null;
-- 
2.7.4