docs: Assorted fixes

Summary:
- Fix multiple doxygen-style references:
Doxygen docs refer to types with #foo whereas Eolian uses @foo.
In lots of places the old Doxygen docs have been just copied into eo files
without properly translating references.

- Add some missing descriptions:
Empty doc tags like [[]] should not be used. Please try at least to provide
a single-line comment, and we can improve that later.
There are still lots of empty doc tags, and their authors will be notified.

Test Plan: Only docs change. make doc and DocFX still work.

Reviewers: zmike, cedric, bu5hm4n

Reviewed By: zmike

Subscribers: #reviewers, foo, #committers

Tags: #efl

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

diff --git a/src/lib/efl/interfaces/efl_gfx_stack.eo b/src/lib/efl/interfaces/efl_gfx_stack.eo
index c2e8c8f..3784358 100644 (file)
--- a/src/lib/efl/interfaces/efl_gfx_stack.eo
+++ b/src/lib/efl/interfaces/efl_gfx_stack.eo
@@ -32,7 +32,7 @@ interface @beta Efl.Gfx.Stack
          }
          values {
             l: short; [[The number of the layer to place the object on.
-                        Must be between #EFL_GFX_STACK_LAYER_MIN and #EFL_GFX_STACK_LAYER_MAX.]]
+                        Must be between @Efl.Gfx.Stack_Layer_Min and @Efl.Gfx.Stack_Layer_Max.]]
          }
       }
       @property below {
@@ -43,8 +43,8 @@ interface @beta Efl.Gfx.Stack
               objects on layers below the one $obj is placed at.
 
               See also @.layer.get(), @.layer.set() and @.below.get()]]
-            return: Efl.Gfx.Stack @warn_unused; [[The #Efl_Gfx_Stack directly below $obj, if any,
-                                                    or $null, if none]]
+            return: Efl.Gfx.Stack @warn_unused; [[The @Efl.Gfx.Stack object directly below $obj, if any,
+                                                    or $null, if none.]]
          }
       }
       @property above {
@@ -55,8 +55,8 @@ interface @beta Efl.Gfx.Stack
               objects on layers above the one $obj is placed at.
 
               See also @.layer.get(), @.layer.set() and @.below.get()]]
-            return: Efl.Gfx.Stack @warn_unused; [[The #Efl_Gfx_Stack directly below $obj, if any,
-                                                    or $null, if none]]
+            return: Efl.Gfx.Stack @warn_unused; [[The @Efl.Gfx.Stack object directly below $obj, if any,
+                                                    or $null, if none.]]
          }
       }
       stack_below {

diff --git a/src/lib/efl/interfaces/efl_ui_scrollbar.eo b/src/lib/efl/interfaces/efl_ui_scrollbar.eo
index 18b9e05..8d2fd49 100644 (file)
--- a/src/lib/efl/interfaces/efl_ui_scrollbar.eo
+++ b/src/lib/efl/interfaces/efl_ui_scrollbar.eo
@@ -3,7 +3,7 @@ enum Efl.Ui.Scrollbar_Mode
    auto = 0, [[Visible if necessary]]
    on, [[Always visible]]
    off, [[Always invisible]]
-   last [[]]
+   last [[For internal use only]]
 }
 
 enum Efl.Ui.Scrollbar_Direction

diff --git a/src/lib/elementary/efl_ui_grid_default_item.eo b/src/lib/elementary/efl_ui_grid_default_item.eo
index 625482e..4cbe74e 100644 (file)
--- a/src/lib/elementary/efl_ui_grid_default_item.eo
+++ b/src/lib/elementary/efl_ui_grid_default_item.eo
@@ -7,8 +7,8 @@ class @beta Efl.Ui.Grid_Default_Item extends Efl.Ui.Grid_Item implements
 {
    [[Grid Default Item class.
      This class need to be sub object of list widget.
-     text and contents can be appliable by efl_text,
-     efl_content or efl_part APIs.]]
+     Text and contents can be set using @Efl.Text,
+     @Efl.Content or @Efl.Part.]]
    data: null;
    parts {
      icon: Efl.Ui.Grid_Default_Item_Part_Icon; [[]]

diff --git a/src/lib/elementary/efl_ui_win.eo b/src/lib/elementary/efl_ui_win.eo
index ad122da..7c40b0f 100644 (file)
--- a/src/lib/elementary/efl_ui_win.eo
+++ b/src/lib/elementary/efl_ui_win.eo
@@ -215,7 +215,7 @@ class @beta Efl.Ui.Win extends Efl.Ui.Widget implements Efl.Canvas.Scene, Efl.Ac
             legacy: null;
          }
          values {
-            type: Efl.Ui.Win_Indicator_Mode; [[The mype, one of #Efl_Ui_Win_Indicator_Mode.]]
+            type: Efl.Ui.Win_Indicator_Mode; [[The mype, one of @Efl.Ui.Win_Indicator_Mode.]]
          }
       }
       @property keyboard_mode {
@@ -226,7 +226,7 @@ class @beta Efl.Ui.Win extends Efl.Ui.Widget implements Efl.Canvas.Scene, Efl.Ac
             [[Get the keyboard mode of the window.]]
          }
          values {
-            mode: Efl.Ui.Win_Keyboard_Mode; [[The mode, one of #Efl_Ui_Win_Keyboard_Mode.]]
+            mode: Efl.Ui.Win_Keyboard_Mode; [[The mode, one of @Efl.Ui.Win_Keyboard_Mode.]]
          }
       }
       @property wm_available_rotations {
@@ -435,7 +435,7 @@ class @beta Efl.Ui.Win extends Efl.Ui.Widget implements Efl.Canvas.Scene, Efl.Ac
          }
          values {
             urgent: Efl.Ui.Win_Urgent_Mode;
-                [[The mode of a urgent window, one of #Efl_Ui_Win_Urgent_Mode.]]
+                [[The mode of a urgent window, one of @Efl.Ui.Win_Urgent_Mode.]]
          }
       }
       @property modal {
@@ -448,7 +448,7 @@ class @beta Efl.Ui.Win extends Efl.Ui.Widget implements Efl.Canvas.Scene, Efl.Ac
             legacy: null;
          }
          values {
-            modal: Efl.Ui.Win_Modal_Mode; [[The mode of a window, one of #Efl_Ui_Win_Modal_Mode.]]
+            modal: Efl.Ui.Win_Modal_Mode; [[The mode of a window, one of @Efl.Ui.Win_Modal_Mode.]]
          }
       }
       @property noblank {