From 5a447ed3273b6b80d9e48aea3cddfcafa1cb8c33 Mon Sep 17 00:00:00 2001 From: Xavi Artigas Date: Mon, 7 Oct 2019 16:40:50 +0200 Subject: [PATCH] docs: Remove redundant documentation Lots of EO files had the same information at the property and set/get level. Removed the redundant bits, and moved to the property level the common ones. Set and Get documentation should be used only to clarify setter-only or getter-only behavior. --- src/lib/ecore/efl_loop_consumer.eo | 5 +-- src/lib/edje/efl_canvas_layout_part.eo | 1 - src/lib/edje/efl_layout_calc.eo | 2 - src/lib/edje/efl_layout_group.eo | 2 +- src/lib/efl/interfaces/efl_gfx_filter.eo | 1 - src/lib/efl/interfaces/efl_gfx_hint.eo | 1 - .../efl_gfx_image_load_controller.eo | 20 +++------ src/lib/efl/interfaces/efl_model.eo | 2 +- src/lib/efl/interfaces/efl_ui_drag.eo | 12 ------ src/lib/efl/interfaces/efl_ui_i18n.eo | 2 - src/lib/efl/interfaces/efl_ui_menu.eo | 8 ++-- src/lib/elementary/efl_access_text.eo | 3 +- src/lib/elementary/efl_access_value.eo | 3 +- src/lib/elementary/efl_ui_calendar.eo | 42 +++++++------------ .../efl_ui_internal_text_scroller.eo | 4 +- src/lib/elementary/efl_ui_theme.eo | 1 - src/lib/elementary/efl_ui_view_model.eo | 2 - src/lib/elementary/efl_ui_widget.eo | 34 ++++----------- src/lib/elementary/efl_ui_win.eo | 21 ++-------- src/lib/evas/canvas/efl_canvas_group.eo | 1 - 20 files changed, 45 insertions(+), 122 deletions(-) diff --git a/src/lib/ecore/efl_loop_consumer.eo b/src/lib/ecore/efl_loop_consumer.eo index 35053265ea..e384240c0b 100644 --- a/src/lib/ecore/efl_loop_consumer.eo +++ b/src/lib/ecore/efl_loop_consumer.eo @@ -9,12 +9,11 @@ abstract Efl.Loop_Consumer extends Efl.Object c_prefix: efl_loop; methods { @property loop { - [[The loop to which this object belongs to.]] + [[Handle of the loop this object belongs to.]] get { - [[Gets a handle to the loop.]] } values { - loop: Efl.Loop; [[Efl loop]] + loop: Efl.Loop; [[Efl loop.]] } } future_resolved @const { diff --git a/src/lib/edje/efl_canvas_layout_part.eo b/src/lib/edje/efl_canvas_layout_part.eo index eed8aaf0de..9346cc68d5 100644 --- a/src/lib/edje/efl_canvas_layout_part.eo +++ b/src/lib/edje/efl_canvas_layout_part.eo @@ -27,7 +27,6 @@ class @beta Efl.Canvas.Layout_Part extends Efl.Object implements Efl.Gfx.Entity, @property part_type { [[Type of this part in the layout.]] get { - [[Returns the type of the part.]] } values { type: Efl.Canvas.Layout_Part_Type(Efl.Canvas.Layout_Part_Type.none); diff --git a/src/lib/edje/efl_layout_calc.eo b/src/lib/edje/efl_layout_calc.eo index 0417629b0e..1f77db64fc 100644 --- a/src/lib/edje/efl_layout_calc.eo +++ b/src/lib/edje/efl_layout_calc.eo @@ -26,10 +26,8 @@ interface Efl.Layout.Calc event. ]] set { - [[Enable or disable auto-update of size hints.]] } get { - [[Whether this object updates its size hints automatically.]] } values { update: bool(false); [[Whether or not update the size hints.]] diff --git a/src/lib/edje/efl_layout_group.eo b/src/lib/edje/efl_layout_group.eo index df1d9dc5ac..77113abc81 100644 --- a/src/lib/edje/efl_layout_group.eo +++ b/src/lib/edje/efl_layout_group.eo @@ -111,7 +111,7 @@ interface Efl.Layout.Group See also @Efl.Canvas.Layout_Part.part_type. ]] - get { [[Returns $true if the part exists in the EDC group.]] } + get {} keys { part: string; [[The part name to check.]] } diff --git a/src/lib/efl/interfaces/efl_gfx_filter.eo b/src/lib/efl/interfaces/efl_gfx_filter.eo index ed74c087fd..ecb306f5f3 100644 --- a/src/lib/efl/interfaces/efl_gfx_filter.eo +++ b/src/lib/efl/interfaces/efl_gfx_filter.eo @@ -59,7 +59,6 @@ interface @beta Efl.Gfx.Filter by using the function 'padding_set' in the Lua program. ]] get { - [[Gets the padding required to apply this filter.]] } values { l: int; [[Padding on the left]] diff --git a/src/lib/efl/interfaces/efl_gfx_hint.eo b/src/lib/efl/interfaces/efl_gfx_hint.eo index 5906b2523f..3511592ead 100644 --- a/src/lib/efl/interfaces/efl_gfx_hint.eo +++ b/src/lib/efl/interfaces/efl_gfx_hint.eo @@ -99,7 +99,6 @@ interface Efl.Gfx.Hint ]] } get { - [[Get the "intrinsic" maximum size of this object.]] } values { sz: Eina.Size2D; [[Maximum size (hint) in pixels.]] diff --git a/src/lib/efl/interfaces/efl_gfx_image_load_controller.eo b/src/lib/efl/interfaces/efl_gfx_image_load_controller.eo index 8f6164760f..ab2b7f77d7 100644 --- a/src/lib/efl/interfaces/efl_gfx_image_load_controller.eo +++ b/src/lib/efl/interfaces/efl_gfx_image_load_controller.eo @@ -53,18 +53,15 @@ interface Efl.Gfx.Image_Load_Controller size instead of its original size. This can save a lot of memory and is important for scalable types like SVG. + EFL will try to load an image of the requested size but does + not guarantee an exact match between the request and the loaded + image dimensions. + By default, the load size is not specified, so it is $[0x0]. ]] set { - [[Requests the canvas to load the image at the given size. - - EFL will try to load an image of the requested size but does - not guarantee an exact match between the request and the loaded - image dimensions. - ]] } get { - [[Returns the requested load size.]] } values { size: Eina.Size2D; [[The image load size.]] @@ -139,11 +136,7 @@ interface Efl.Gfx.Image_Load_Controller Powers of two (2, 4, 8, ...) are best supported (especially with JPEG). ]] - set { - [[Requests the image loader to scale down by $div times. - Call this before starting the actual image load. - ]] - } + set {} get {} values { div: int; [[The scale down dividing factor.]] @@ -156,8 +149,7 @@ interface Efl.Gfx.Image_Load_Controller loading to a preload stage and/or data load later on rather than at the start when the load begins (e.g. when file is set). ]] - set { - } + set {} get {} values { skip: bool; [[$true if header is to be skipped.]] diff --git a/src/lib/efl/interfaces/efl_model.eo b/src/lib/efl/interfaces/efl_model.eo index 6492f76714..3d186f30b6 100644 --- a/src/lib/efl/interfaces/efl_model.eo +++ b/src/lib/efl/interfaces/efl_model.eo @@ -95,7 +95,7 @@ interface Efl.Model The future can also be canceled if the model itself gets destroyed. - ]] + ]] params { @in property: string; [[Property name.]] } diff --git a/src/lib/efl/interfaces/efl_ui_drag.eo b/src/lib/efl/interfaces/efl_ui_drag.eo index 36a5aa0365..8d01bdd413 100644 --- a/src/lib/efl/interfaces/efl_ui_drag.eo +++ b/src/lib/efl/interfaces/efl_ui_drag.eo @@ -25,14 +25,9 @@ interface @beta Efl.Ui.Drag in the draggable part theme is 1, and right if it is -1. ]] set { - [[Sets the draggable object location. - - This places the draggable object at the given location. - ]] return: bool; [[$true on success, $false otherwise]] } get { - [[Gets the draggable object location.]] return: bool; [[$true on success, $false otherwise]] } values { @@ -50,11 +45,9 @@ interface @beta Efl.Ui.Drag the scroller's content. ]] set { - [[Sets the size of the draggable object.]] return: bool; [[$true on success, $false otherwise]] } get { - [[Gets the size of the dradgable object.]] return: bool; [[$true on success, $false otherwise]] } values { @@ -70,7 +63,6 @@ interface @beta Efl.Ui.Drag reference documentation for more information. ]] get { - [[Gets the draggable direction.]] return: Efl.Ui.Drag_Dir; [[The direction(s) premitted for drag.]] } } @@ -87,11 +79,9 @@ interface @beta Efl.Ui.Drag See also @.drag_page. ]] set { - [[Sets the x,y step increments for a draggable object.]] return: bool; [[$true on success, $false otherwise]] } get { - [[Gets the x and y step increments for the draggable object.]] return: bool; [[$true on success, $false otherwise]] } values { @@ -128,11 +118,9 @@ interface @beta Efl.Ui.Drag See also @.drag_step. ]] set { - [[Sets the x,y page step increment values.]] return: bool; [[$true on success, $false otherwise]] } get { - [[Gets the x,y page step increments for the draggable object.]] return: bool; [[$true on success, $false otherwise]] } values { diff --git a/src/lib/efl/interfaces/efl_ui_i18n.eo b/src/lib/efl/interfaces/efl_ui_i18n.eo index af37b13f8f..15e48bb5f9 100644 --- a/src/lib/efl/interfaces/efl_ui_i18n.eo +++ b/src/lib/efl/interfaces/efl_ui_i18n.eo @@ -30,10 +30,8 @@ interface @beta Efl.Ui.I18n @property language { [[The (human) language for this object.]] set { - [[Sets the language for this object.]] } get { - [[Gets the language for this object.]] } values { language: string; [[The current language.]] diff --git a/src/lib/efl/interfaces/efl_ui_menu.eo b/src/lib/efl/interfaces/efl_ui_menu.eo index ca76bf2639..2c5002267e 100644 --- a/src/lib/efl/interfaces/efl_ui_menu.eo +++ b/src/lib/efl/interfaces/efl_ui_menu.eo @@ -2,32 +2,32 @@ interface @beta Efl.Ui.Menu { [[Efl UI menu interface]] methods { @property selected_item { + [[Get the selected item in the widget.]] get { - [[Get the selected item in the widget.]] } values { item: Efl.Ui.Item; [[The selected item or $null.]] } } @property first_item { + [[Get the first item in the widget.]] get { - [[Get the first item in the widget.]] } values { item: Efl.Ui.Item; [[The first item or $null.]] } } @property last_item { + [[Get the last item in the widget.]] get { - [[Get the last item in the widget.]] } values { item: Efl.Ui.Item; [[The last item or $null.]] } } @property items { + [[Returns a list of the widget items.]] get { - [[Returns a list of the widget item.]] return: iterator @move @no_unused; [[Iterator to widget items]] } } diff --git a/src/lib/elementary/efl_access_text.eo b/src/lib/elementary/efl_access_text.eo index 02a7e1688a..0fe97c4a32 100644 --- a/src/lib/elementary/efl_access_text.eo +++ b/src/lib/elementary/efl_access_text.eo @@ -88,9 +88,8 @@ interface @beta Efl.Access.Text } } @property caret_offset @protected @beta { - [[Caret offset property]] + [[Offset position of the caret (cursor).]] get { - [[Gets offset position of caret (cursor)]] } set { return: bool; [[$true if caret was successfully moved, $false otherwise.]] diff --git a/src/lib/elementary/efl_access_value.eo b/src/lib/elementary/efl_access_value.eo index c2b8107a86..8f94b79c32 100644 --- a/src/lib/elementary/efl_access_value.eo +++ b/src/lib/elementary/efl_access_value.eo @@ -3,9 +3,8 @@ interface @beta Efl.Access.Value [[Elementary Access value interface]] methods { @property value_and_text @protected @beta { - [[Value and text property]] + [[Value and text displayed bye accessible widget.]] get { - [[Gets value displayed by a accessible widget.]] } set { return: bool; [[$true if setting widgets value has succeeded, otherwise $false .]] diff --git a/src/lib/elementary/efl_ui_calendar.eo b/src/lib/elementary/efl_ui_calendar.eo index 1d522f6385..8f9d9db434 100644 --- a/src/lib/elementary/efl_ui_calendar.eo +++ b/src/lib/elementary/efl_ui_calendar.eo @@ -29,7 +29,7 @@ class @beta Efl.Ui.Calendar extends Efl.Ui.Layout_Base @property first_day_of_week { [[The first day of week to use on calendar widgets. - This is the day that will appear in the left-most column (eg. Monday + This is the day that will appear in the left-most column (e.g. Monday in France or Sunday in the US). ]] values { @@ -40,19 +40,15 @@ class @beta Efl.Ui.Calendar extends Efl.Ui.Layout_Base @property date_min { [[Minimum date on calendar.]] set { - [[Set the minimum date on calendar. - - Set the minimum date, changing the displayed month or year if needed. - Displayed day also to be disabled if it is smaller than minimum date. - If the minimum date is greater than current maximum date, the minimum - date would be changed to the maximum date with returning $false. + [[Setting the minimum date changes the displayed month or year if needed. + Displayed days may also be disabled if they are smaller than minimum date. + If the minimum date is greater than @.date_max date, the minimum + date will be changed to the maximum date returning $false. ]] - return: bool; [[$true, on success, $false otherwise]] + return: bool; [[$true on success.]] } get { - [[Get the minimum date. - - Default value is 1 JAN,1902. + [[Default value is 1 JAN,1902. ]] } values { @@ -62,19 +58,15 @@ class @beta Efl.Ui.Calendar extends Efl.Ui.Layout_Base @property date_max { [[Maximum date on calendar.]] set { - [[Set the maximum date on calendar. - - Set the maximum date, changing the displayed month or year if needed. - Displayed day also to be disabled if it is bigger than maximum date. - If the maximum date is less than current minimum date, the maximum date - would be changed to the minimum date with returning $false. + [[Setting the maximum date changes the displayed month or year if needed. + Displayed days may also be disabled if they are bigger than maximum date. + If the maximum date is less than @.date_min, the maximum date + will be changed to the minimum date returning $false. ]] - return: bool; [[$true, on success, $false otherwise]] + return: bool; [[$true on success.]] } get { - [[Get the maximum date. - - Default maximum year is -1. + [[Default maximum year is -1. Default maximum day and month are 31 and DEC. If the maximum year is a negative value, it will be limited depending @@ -88,12 +80,10 @@ class @beta Efl.Ui.Calendar extends Efl.Ui.Layout_Base @property date { [[The selected date on calendar.]] set { - [[Set the selected date. If the date is greater than the maximum date, - the date would be changed to the maximum date with returning $false. - In the opposite case with the minimum date, - this would give the same result. + [[Dates will be clamped between @.date_min and @.date_max, returning $false + when trying to set out-of-bounds values. ]] - return: bool; [[$true, on success, $false otherwise]] + return: bool; [[$true on success.]] } get { } diff --git a/src/lib/elementary/efl_ui_internal_text_scroller.eo b/src/lib/elementary/efl_ui_internal_text_scroller.eo index a05300dbd0..3108000d83 100644 --- a/src/lib/elementary/efl_ui_internal_text_scroller.eo +++ b/src/lib/elementary/efl_ui_internal_text_scroller.eo @@ -16,9 +16,8 @@ class @beta Efl.Ui.Internal_Text_Scroller extends Efl.Ui.Scroller ]] methods { @property scroller_mode { - [[Mode of operation for the scroller]] + [[Mode of operation for the scroller, either default (singleline) or multiline.]] set { - [[Sets mode to either default (singleline) or multiline]] } values { mode: Efl.Ui.Text_Scroller_Mode; @@ -27,7 +26,6 @@ class @beta Efl.Ui.Internal_Text_Scroller extends Efl.Ui.Scroller @property viewport_clip { [[The viewport's clip object]] get { - [[Gets viewport's clip object]] } values { clip: Efl.Object; diff --git a/src/lib/elementary/efl_ui_theme.eo b/src/lib/elementary/efl_ui_theme.eo index a11381d2c3..9320d0afed 100644 --- a/src/lib/elementary/efl_ui_theme.eo +++ b/src/lib/elementary/efl_ui_theme.eo @@ -11,7 +11,6 @@ class @beta Efl.Ui.Theme extends Efl.Object is set. ]] get { - [[Gets the default theme handle.]] } values { theme: Efl.Ui.Theme; [[The default theme handle]] diff --git a/src/lib/elementary/efl_ui_view_model.eo b/src/lib/elementary/efl_ui_view_model.eo index ebc25dd342..26e29afbcb 100644 --- a/src/lib/elementary/efl_ui_view_model.eo +++ b/src/lib/elementary/efl_ui_view_model.eo @@ -120,10 +120,8 @@ class Efl.Ui.View_Model extends Efl.Composite_Model This can only be applied at construction time.]] get { - [[Get the state of the automatic binding of children object.]] } set { - [[Set the state of the automatic binding of children object.]] } values { enable: bool; [[Do you automatically bind children. Default to true.]] diff --git a/src/lib/elementary/efl_ui_widget.eo b/src/lib/elementary/efl_ui_widget.eo index ff6f94ffe3..14375c2137 100644 --- a/src/lib/elementary/efl_ui_widget.eo +++ b/src/lib/elementary/efl_ui_widget.eo @@ -39,17 +39,13 @@ abstract Efl.Ui.Widget extends Efl.Canvas.Group implements Efl.Access.Object, If using X cursors, a definition of all the valid cursor names is listed on Elementary_Cursors.h. If an invalid name is set the default cursor will be used. + + If $cursor is set to $null it will be reset to the default one. ]] set { - [[Sets or unsets the current cursor. - - If $cursor is $null this function will reset the cursor - to the default one. - ]] return: bool; [[$true if successful.]] } get { - [[Returns the current cursor name.]] } values { cursor: string; [[The cursor name, defined either @@ -64,11 +60,9 @@ abstract Efl.Ui.Widget extends Efl.Canvas.Group implements Efl.Access.Object, setting its style with this property. ]] set { - [[Sets a style for the current cursor. Call after @.cursor.set.]] return: bool; [[$true if successful.]] } get { - [[Returns the current cursor style name.]] } values { style: string; [[A specific style to use, e.g. default, @@ -82,11 +76,9 @@ abstract Efl.Ui.Widget extends Efl.Canvas.Group implements Efl.Access.Object, i.e. from the display manager. ]] set { - [[Enables or disables theme cursors.]] return: bool; [[$true if successful.]] } get { - [[Returns the current state of theme cursors search.]] } values { allow: bool(true); [[Whether to use theme cursors.]] @@ -100,7 +92,6 @@ abstract Efl.Ui.Widget extends Efl.Canvas.Group implements Efl.Access.Object, function unless you're implementing a widget. ]] set { - [[Sets the new resize object for this widget.]] } values { sobj: Efl.Canvas.Object; @@ -113,21 +104,17 @@ abstract Efl.Ui.Widget extends Efl.Canvas.Group implements Efl.Access.Object, Each widget may handle the disabled state differently, but overall disabled widgets shall not respond to any input events. This is $false by default, meaning the widget is enabled. + + Disabling a widget will disable all its children recursively, + but only this widget will be marked as disabled internally. + + This will return $true if any widget in the parent hierarchy + is disabled. Re-enabling that parent may in turn change the + disabled state of this widget. ]] set { - [[Enables or disables this widget. - - Disabling a widget will disable all its children recursively, - but only this widget will be marked as disabled internally. - ]] } get { - [[Returns whether the widget is disabled. - - This will return $true if any widget in the parent hierarchy - is disabled. Re-enabling that parent may in turn change the - disabled state of this widget. - ]] } values { disabled: bool(false); [[$true if the widget is disabled.]] @@ -145,13 +132,11 @@ abstract Efl.Ui.Widget extends Efl.Canvas.Group implements Efl.Access.Object, at construction time of the object (inside $efl_add in C). ]] set { - [[Can only be called during construction, before finalize.]] return: Eina.Error; [[Whether the style was successfully applied or not, see the Efl.Ui.Theme.Apply_Error subset of @Eina.Error for more information.]] } get { - [[Returns the current style of a widget.]] } values { style: string; @@ -354,7 +339,6 @@ abstract Efl.Ui.Widget extends Efl.Canvas.Group implements Efl.Access.Object, displayed. ]] get { - [[This is a read-only property.]] } values { region: Eina.Rect; [[The rectangle area.]] diff --git a/src/lib/elementary/efl_ui_win.eo b/src/lib/elementary/efl_ui_win.eo index bec6fdbf51..bca1b4a574 100644 --- a/src/lib/elementary/efl_ui_win.eo +++ b/src/lib/elementary/efl_ui_win.eo @@ -418,7 +418,6 @@ class Efl.Ui.Win extends Efl.Ui.Widget implements Efl.Canvas.Scene, Efl.Access.W Note: Once set, it cannot be modified afterwards. ]] set { - [[Name can only be set before finalize.]] } get { } @@ -435,12 +434,12 @@ class Efl.Ui.Win extends Efl.Ui.Widget implements Efl.Canvas.Scene, Efl.Access.W creation time, before finalize. In C this means inside $efl_add(). Note: Once set, it cannot be modified afterward. + + If the object is not window object, returns @Efl.Ui.Win_Type.unknown. ]] set { - [[Type can on be set before finalize.]] } get { - [[If the object is not window object, returns $unknown.]] } values { type: Efl.Ui.Win_Type(Efl.Ui.Win_Type.basic); [[Window type]] @@ -495,8 +494,6 @@ class Efl.Ui.Win extends Efl.Ui.Widget implements Efl.Canvas.Scene, Efl.Access.W set { } get { - [[This will return the value of "accel_preference" when the window - was created.]] } } @property alpha { @@ -741,20 +738,14 @@ class Efl.Ui.Win extends Efl.Ui.Widget implements Efl.Canvas.Scene, Efl.Access.W } } @property focus_highlight_enabled { - [[Whether focus highlight is enabled or not. + [[Whether focus highlight is enabled or not on this window, regardless of the global setting. See also @.focus_highlight_style. See also @.focus_highlight_animate. ]] set { - [[Set the enabled status for the focus highlight in a window. - - This function will enable or disable the focus highlight, - regardless of the global setting for it. - ]] } get { - [[Get the enabled value of the focus highlight for this window.]] } values { enabled: bool; [[The enabled value for the highlight.]] @@ -785,14 +776,8 @@ class Efl.Ui.Win extends Efl.Ui.Widget implements Efl.Canvas.Scene, Efl.Access.W See also @.focus_highlight_enabled. ]] set { - [[Set the animate status for the focus highlight for this window. - - This function will enable or disable the animation of focus - highlight. - ]] } get { - [[Get the animate value of the focus highlight for this window.]] } values { animate: bool; [[The enabled value for the highlight animation.]] diff --git a/src/lib/evas/canvas/efl_canvas_group.eo b/src/lib/evas/canvas/efl_canvas_group.eo index f129ce056d..500b521f88 100644 --- a/src/lib/evas/canvas/efl_canvas_group.eo +++ b/src/lib/evas/canvas/efl_canvas_group.eo @@ -111,7 +111,6 @@ class Efl.Canvas.Group extends Efl.Canvas.Object clipper: const(Efl.Canvas.Object); [[A clipper rectangle.]] } get { - [[Get the internal clipper.]] } } }