docs: Add detailed text styling information

Summary:
More detailed descriptions for each attribute.
Relationship between attributes.
Default values.
Links to direct API methods for the corresponding property.
General text overhaul and formatting.

Test Plan: Builds and passes tests. Generate docgen or DocFX documentation and enjoy your new Text styling descriptions!

Reviewers: ali.alzyod

Reviewed By: ali.alzyod

Subscribers: AbdullehGhujeh, cedric, #reviewers, #committers, woohyun, bu5hm4n

Tags: #efl

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

4 files changed, 456 insertions, 499 deletions

diff --git a/src/lib/efl/interfaces/efl_text_font.eo b/src/lib/efl/interfaces/efl_text_font.eo
index 836835c2a6..dce81a7e10 100644
--- a/src/lib/efl/interfaces/efl_text_font.eo
+++ b/src/lib/efl/interfaces/efl_text_font.eo
@@ -1,53 +1,53 @@
 import efl_gfx_types;
 enum @beta Efl.Text_Font_Weight {
-   [[Type of font weight]]
-   normal, [[Normal font weight]]
-   thin, [[Thin font weight]]
-   ultralight, [[Ultralight font weight]]
-   extralight, [[Extralight font weight]]
-   light, [[Light font weight]]
-   book, [[Book font weight]]
-   medium, [[Medium font weight]]
-   semibold, [[Semibold font weight]]
-   bold, [[Bold font weight]]
-   ultrabold, [[Ultrabold font weight]]
-   extrabold, [[Extrabold font weight]]
-   black, [[Black font weight]]
-   extrablack, [[Extrablack font weight]]
+   [[Type of font weight.]]
+   normal, [[Normal font weight.]]
+   thin, [[Thin font weight.]]
+   ultralight, [[Ultralight font weight.]]
+   extralight, [[Extralight font weight.]]
+   light, [[Light font weight.]]
+   book, [[Book font weight.]]
+   medium, [[Medium font weight.]]
+   semibold, [[Semibold font weight.]]
+   bold, [[Bold font weight.]]
+   ultrabold, [[Ultrabold font weight.]]
+   extrabold, [[Extrabold font weight.]]
+   black, [[Black font weight.]]
+   extrablack, [[Extrablack font weight.]]
 }
 
 enum @beta Efl.Text_Font_Width {
-   [[Type of font width]]
-   normal, [[Normal font width]]
-   ultracondensed, [[Ultracondensed font width]]
-   extracondensed, [[Extracondensed font width]]
-   condensed, [[Condensed font width]]
-   semicondensed, [[Semicondensed font width]]
-   semiexpanded, [[Semiexpanded font width]]
-   expanded, [[Expanded font width]]
-   extraexpanded, [[Extraexpanded font width]]
-   ultraexpanded, [[Ultraexpanded font width]]
+   [[Type of font width.]]
+   normal, [[Normal font width.]]
+   ultracondensed, [[Ultracondensed font width.]]
+   extracondensed, [[Extracondensed font width.]]
+   condensed, [[Condensed font width.]]
+   semicondensed, [[Semicondensed font width.]]
+   semiexpanded, [[Semiexpanded font width.]]
+   expanded, [[Expanded font width.]]
+   extraexpanded, [[Extraexpanded font width.]]
+   ultraexpanded, [[Ultraexpanded font width.]]
 }
 
 enum @beta Efl.Text_Font_Slant {
-    [[Type of font slant]]
-    normal, [[Normal font slant]]
-    oblique, [[Oblique font slant]]
-    italic, [[Italic font slant]]
+    [[Type of font slant.]]
+    normal, [[Normal font slant.]]
+    oblique, [[Oblique font slant.]]
+    italic, [[Italic font slant.]]
 }
 
 /* FIXME: It needs to support "normal" option for non-color bitmap font.
    For supporting "normal" option, S/W glyph drawing engine should be updated.
  */
 enum @beta Efl.Text_Font_Bitmap_Scalable {
-   [[Scalable of bitmap fonts
+   [[Scalable of bitmap fonts.
    ]]
    none = 0,         [[Disable scalable feature for bitmap fonts.]]
    color = (1 << 0), [[Enable scalable feature for color bitmap fonts.]]
 }
 
 interface @beta Efl.Text_Font {
-   [[Font settings of the text
+   [[Font settings for text.
    ]]
    c_prefix: efl_text;
    methods {
@@ -105,42 +105,42 @@ interface @beta Efl.Text_Font {
       }
 
       @property font_fallbacks {
-         [[Comma-separated list of font fallbacks
+         [[Comma-separated list of font fallbacks.
 
            Will be used in case the primary font isn't available.
          ]]
          values {
-            font_fallbacks: string; [[Font name fallbacks]]
+            font_fallbacks: string; [[List of fallback font names.]]
          }
       }
 
       @property font_weight {
          [[Type of weight of the displayed font
 
-           Default is @Efl.Text_Font_Weight.normal\.
+           Default is @Efl.Text_Font_Weight.normal.
          ]]
          values {
-            font_weight: Efl.Text_Font_Weight; [[Font weight]]
+            font_weight: Efl.Text_Font_Weight; [[Font weight.]]
          }
       }
 
       @property font_slant {
-         [[Type of slant of the displayed font
+         [[Type of slant of the displayed font.
 
-           Default is @Efl.Text_Font_Slant.normal\.
+           Default is @Efl.Text_Font_Slant.normal.
          ]]
          values {
-            style: Efl.Text_Font_Slant; [[Font slant]]
+            style: Efl.Text_Font_Slant; [[Font slant.]]
          }
       }
 
       @property font_width {
-         [[Type of width of the displayed font
+         [[Type of width of the displayed font.
 
-           Default is @Efl.Text_Font_Width.normal\.
+           Default is @Efl.Text_Font_Width.normal.
          ]]
          values {
-            width: Efl.Text_Font_Width; [[Font width]]
+            width: Efl.Text_Font_Width; [[Font width.]]
          }
       }
 
@@ -153,19 +153,19 @@ interface @beta Efl.Text_Font {
            "auto" to use the system locale, or "none".
          ]]
          values {
-            lang: string; [[Language]]
+            lang: string; [[Language code.]]
          }
       }
 
       @property font_bitmap_scalable {
            [[The bitmap fonts have fixed size glyphs for several available sizes.
              Basically, it is not scalable. But, it needs to be scalable for some use cases.
-             (ex. colorful emoji fonts)
+             (e.g. colorful emoji fonts)
 
-             Default is @Efl.Text_Font_Bitmap_Scalable.none\.
+             Default is @Efl.Text_Font_Bitmap_Scalable.none.
            ]]
            values {
-              scalable: Efl.Text_Font_Bitmap_Scalable; [[Scalable]]
+              scalable: Efl.Text_Font_Bitmap_Scalable; [[Scalable.]]
            }
       }
    }
diff --git a/src/lib/efl/interfaces/efl_text_format.eo b/src/lib/efl/interfaces/efl_text_format.eo
index 7ecc8fead4..05d5226407 100644
--- a/src/lib/efl/interfaces/efl_text_format.eo
+++ b/src/lib/efl/interfaces/efl_text_format.eo
@@ -1,22 +1,23 @@
 enum @beta Efl.Text_Format_Wrap {
-   [[Wrap mode of the text (not in effect if not multiline)]]
-   none, [[No wrapping]]
-   char, [[Wrap mode character]]
-   word, [[Wrap mode word]]
-   mixed, [[Wrap mode mixed]]
-   hyphenation [[Wrap mode hyphenation]]
+   [[Wrapping policy of the text.]]
+   none, [[No wrapping.]]
+   char, [[Wrap at character boundaries.]]
+   word, [[Wrap at word boundaries.]]
+   mixed, [[Wrap at word boundaries if possible, at any character if not.]]
+   hyphenation [[Hyphenate if possible, otherwise try word boundaries or
+                 at any character.]]
 }
 
 enum @beta Efl.Text_Format_Horizontal_Alignment_Auto_Type {
-   [[Auto-horizontal alignment of the text]]
-   none,   [[No auto-alignment rule]]
-   normal, [[Respects LTR/RTL (bidirectional) settings]]
-   locale, [[Respects locale's langauge settings]]
-   end     [[Text is places at opposite side of LTR/RTL (bidirectional) settings]]
+   [[Auto-horizontal alignment of the text.]]
+   none,   [[No auto-alignment rule.]]
+   normal, [[Respects LTR/RTL (bidirectional) settings.]]
+   locale, [[Respects locale's language settings.]]
+   end     [[Text is placed at opposite side of LTR/RTL (bidirectional) settings.]]
 }
 
 interface @beta Efl.Text_Format {
-   [[The look and layout of the text
+   [[The look and layout of the text.
 
      The text format can affect the geometry of the text object, as well as
      how characters are presented.
@@ -24,83 +25,96 @@ interface @beta Efl.Text_Format {
    c_prefix: efl_text;
    methods {
       @property ellipsis {
-         [[Ellipsis value (number from -1.0 to 1.0)]]
+         [[Controls automatic addition of ellipsis "..." to replace text which cannot be shown.
+           The value must be a number indicating the position of the ellipsis inside the visible text.
+           $[0.0] means the beginning of the text, $[1.0] means the end of the text, and values in between
+           mean the proportional position inside the text.
+           Any value smaller than 0 or greater than 1 disables ellipsis.
+         ]]
          values
          {
-            value: double; [[Ellipsis value]]
+            value: double; [[Ellipsis value.]]
          }
       }
 
       @property wrap {
-         [[Wrap mode for use in the text]]
+         [[Wrapping policy of the text. Requires @.multiline to be $true.]]
          values {
-            wrap: Efl.Text_Format_Wrap; [[Wrap mode]]
+            wrap: Efl.Text_Format_Wrap; [[Wrap mode.]]
          }
       }
 
       @property multiline {
-         [[Multiline is enabled or not]]
+         [[Enables text to span multiple lines.
+         
+           When $false, new-line characters are ignored and no text wrapping occurs.
+         ]]
          values {
-            enabled: bool; [[$true if multiline is enabled, $false otherwise]]
+            enabled: bool; [[$true if multiline is enabled.]]
          }
       }
 
       @property horizontal_align_auto_type {
-         [[Horizontal alignment of text]]
+         [[Horizontal alignment of text.]]
          values {
-            value: Efl.Text_Format_Horizontal_Alignment_Auto_Type; [[Alignment type]]
+            value: Efl.Text_Format_Horizontal_Alignment_Auto_Type; [[Alignment type.]]
          }
       }
 
       @property horizontal_align {
-         [[Horizontal alignment of text]]
+         [[Horizontal alignment of text. $[0.0] means "left"
+           and $[1.0] means "right".]]
          values {
-            value: double; [[Horizontal alignment value]]
+            value: double; [[Alignment value between $[0.0] and $[1.0].]]
          }
       }
 
       @property vertical_align {
-         [[Vertical alignment of text]]
+         [[Vertical alignment of text.$[0.0] means "top"
+           and $[1.0] means "bottom"]]
          values {
-            value: double; [[Vertical alignment value]]
+            value: double; [[Alignment value between $[0.0] and $[1.0].]]
          }
       }
 
       @property linegap {
-         [[Minimal line gap (top and bottom) for each line in the text
+         [[Minimal line gap (top and bottom) for each line in the text.
 
            $value is absolute size.
          ]]
          values
          {
-            value: double; [[Line gap value]]
+            value: double; [[Line gap value, in pixels.]]
          }
       }
 
       @property linerelgap {
-         [[Relative line gap (top and bottom) for each line in the text
+         [[Relative line gap (top and bottom) for each line in the text.
 
            The original line gap value is multiplied by $value.
          ]]
          values
          {
-            value: double; [[Relative line gap value]]
+            value: double; [[Relative line gap value. $[1.0] means original size.]]
          }
       }
 
       @property tabstops {
-         [[Tabstops value]]
+         [[Size of the tab character.]]
          values
          {
-            value: int; [[Tapstops value]]
+            value: int; [[Size in pixels.]]
          }
       }
 
       @property password {
-         [[Whether text is a password]]
+         [[Enabling this causes all characters to be replaced by @.replacement_char.
+         
+           This is useful for password input boxes.
+         ]]
          values
          {
-            enabled: bool; [[$true if the text is a password, $false otherwise]]
+            enabled: bool; [[$true if the text is a password.]]
          }
       }
 
diff --git a/src/lib/efl/interfaces/efl_text_style.eo b/src/lib/efl/interfaces/efl_text_style.eo
index c42433b317..9b66595558 100644
--- a/src/lib/efl/interfaces/efl_text_style.eo
+++ b/src/lib/efl/interfaces/efl_text_style.eo
@@ -1,248 +1,257 @@
 enum @beta Efl.Text_Style_Backing_Type
 {
-   [[Whether to apply backing style to the displayed text or not]]
-   disabled = 0, [[Do not use backing]]
-   enabled,      [[Use backing style]]
+   [[Whether to add a background colored rectangle (backing) to each line of text or not.]]
+   disabled = 0, [[Do not use backing.]]
+   enabled,      [[Use backing.]]
 }
 
 enum @beta Efl.Text_Style_Strikethrough_Type
 {
-   [[Whether to apply strikethrough style to the displayed text or not]]
-   disabled = 0, [[Do not use strikethrough]]
-   enabled,      [[Use strikethrough style]]
+   [[Whether to add a strike-through decoration to the displayed text or not.]]
+   disabled = 0, [[Do not use strike-through.]]
+   enabled,      [[Use strike-through.]]
 }
 
 enum @beta Efl.Text_Style_Effect_Type
 {
-   [[Effect to apply to the displayed text]]
-   none = 0, [[No effect]]
+   [[Effect to apply to the displayed text.]]
+   none = 0, [[No effect.]]
 
    // colored with shadow_color
-   shadow, [[Shadow effect]]
-   far_shadow, [[Far shadow effect]]
-   soft_shadow, [[Soft shadow effect]]
-   far_soft_shadow, [[Far and soft shadow effect]]
+   shadow, [[Shadow effect.]]
+   far_shadow, [[Far shadow effect.]]
+   soft_shadow, [[Soft shadow effect.]]
+   far_soft_shadow, [[Far and soft shadow effect.]]
    // colored with glow_color
-   glow, [[Glow effect]]
+   glow, [[Glow effect.]]
    // colored with outline_color
-   outline, [[Outline effect]]
-   soft_outline, [[Soft outline effect]]
+   outline, [[Outline effect.]]
+   soft_outline, [[Soft outline effect.]]
    // colored with outline_color + shadow_color
-   outline_shadow, [[Outline shadow effect]]
-   outline_soft_shadow, [[Outline soft shadow effect]]
+   outline_shadow, [[Outline + shadow effect.]]
+   outline_soft_shadow, [[Outline + soft shadow effect.]]
 }
 
 enum @beta Efl.Text_Style_Shadow_Direction
 {
-   [[Direction of the shadow style, if used]]
-   bottom_right = 0, [[Shadow towards bottom right]]
-   bottom, [[Shadow towards botom]]
-   bottom_left, [[Shadow towards bottom left]]
-   left, [[Shadow towards left]]
-   top_left, [[Shadow towards top left]]
-   top, [[Shadow towards top]]
-   top_right, [[Shadow towards top right]]
-   right, [[Shadow towards right]]
+   [[Direction of the shadow.]]
+   bottom_right = 0, [[Shadow towards bottom right.]]
+   bottom, [[Shadow towards bottom.]]
+   bottom_left, [[Shadow towards bottom left.]]
+   left, [[Shadow towards left.]]
+   top_left, [[Shadow towards top left.]]
+   top, [[Shadow towards top.]]
+   top_right, [[Shadow towards top right.]]
+   right, [[Shadow towards right.]]
 }
 
 enum @beta Efl.Text_Style_Underline_Type
 {
-   [[Underline type of the displayed text]]
-   off = 0, [[Text without underline]]
-   on, [[Underline enabled]]
-   single, [[Underlined with a signle line]]
-   double, [[Underlined with a double line]]
-   dashed, [[Underlined with a dashed line]]
+   [[Type of underline of the displayed text.]]
+   off = 0, [[Text without underline.]]
+   on, [[Underline enabled.]]
+   single, [[Underlined with a single line.]]
+   double, [[Underlined with a double line.]]
+   dashed, [[Underlined with a dashed line.]]
 }
 
 interface @beta Efl.Text_Style {
-   [[Style to apply to the text
+   [[Decorations to add to the text.
 
-     A style can be coloring, effects, underline, strikethrough etc.
+     Decorations can be coloring, effects, underlines, strike-through etc.
    ]]
    c_prefix: efl_text;
    methods {
       @property normal_color {
-         [[Color of text, excluding style]]
+         [[Color of text, excluding decorations like, shadow, outline or glow.]]
          values
          {
-            r: ubyte; [[Red component]]
-            g: ubyte; [[Green component]]
-            b: ubyte; [[Blue component]]
-            a: ubyte; [[Alpha component]]
+            r: ubyte; [[Red component.]]
+            g: ubyte; [[Green component.]]
+            b: ubyte; [[Blue component.]]
+            a: ubyte; [[Alpha component.]]
          }
       }
 
       @property backing_type {
-          [[Enable or disable backing type]]
+         [[Enables rendering of a background rectangle behind each line of text.]]
          values
          {
-            type: Efl.Text_Style_Backing_Type; [[Backing type]]
+            type: Efl.Text_Style_Backing_Type; [[Backing type.]]
          }
       }
 
       @property backing_color {
-          [[Backing color]]
+          [[Color of the background rectangle (backing) behind each line of text.]]
          values
          {
-            r: ubyte; [[Red component]]
-            g: ubyte; [[Green component]]
-            b: ubyte; [[Blue component]]
-            a: ubyte; [[Alpha component]]
+            r: ubyte; [[Red component.]]
+            g: ubyte; [[Green component.]]
+            b: ubyte; [[Blue component.]]
+            a: ubyte; [[Alpha component.]]
          }
       }
 
       @property underline_type {
-         [[Sets an underline style on the text]]
+         [[Underline style for the text.]]
          values
          {
-            type: Efl.Text_Style_Underline_Type; [[Underline type]]
+            type: Efl.Text_Style_Underline_Type; [[Underline type.]]
          }
       }
 
       @property underline_color
       {
-         [[Color of normal underline style]]
+         [[Color of normal underline style.]]
          values
          {
-            r: ubyte; [[Red component]]
-            g: ubyte; [[Green component]]
-            b: ubyte; [[Blue component]]
-            a: ubyte; [[Alpha component]]
+            r: ubyte; [[Red component.]]
+            g: ubyte; [[Green component.]]
+            b: ubyte; [[Blue component.]]
+            a: ubyte; [[Alpha component.]]
          }
       }
 
       @property underline_height
       {
-         [[Height of underline style]]
+         [[Width (in pixels) of the single underline when @.underline_type is
+           @Efl.Text_Style_Underline_Type.single.]]
          values
          {
-            height: double; [[Height]]
+            height: double; [[Underline width in pixels.]]
          }
       }
 
       @property underline_dashed_color
       {
-         [[Color of dashed underline style]]
+         [[Color of the dashed underline. Only valid when @.underline_type is
+           @Efl.Text_Style_Underline_Type.dashed.]]
          values
          {
-            r: ubyte; [[Red component]]
-            g: ubyte; [[Green component]]
-            b: ubyte; [[Blue component]]
-            a: ubyte; [[Alpha component]]
+            r: ubyte; [[Red component.]]
+            g: ubyte; [[Green component.]]
+            b: ubyte; [[Blue component.]]
+            a: ubyte; [[Alpha component.]]
          }
       }
 
       @property underline_dashed_width
       {
-         [[Width of dashed underline style]]
+         [[Length (in pixels) of the dashes when @.underline_type is
+           @Efl.Text_Style_Underline_Type.dashed.]]
          values
          {
-            width: int; [[Width]]
+            width: int; [[Dash length in pixels.]]
          }
       }
 
       @property underline_dashed_gap
       {
-         [[Gap of dashed underline style]]
+         [[Length (in pixels) of the gaps between the dashes when @.underline_type is
+           @Efl.Text_Style_Underline_Type.dashed.]]
          values
          {
-            gap: int; [[Gap]]
+            gap: int; [[Gap length in pixels.]]
          }
       }
 
       @property underline2_color
       {
-         [[Color of underline2 style]]
+         [[Color of the secondary underline. Only valid when @.underline_type is
+           @Efl.Text_Style_Underline_Type.double.]]
          values
          {
-            r: ubyte; [[Red component]]
-            g: ubyte; [[Green component]]
-            b: ubyte; [[Blue component]]
-            a: ubyte; [[Alpha component]]
+            r: ubyte; [[Red component.]]
+            g: ubyte; [[Green component.]]
+            b: ubyte; [[Blue component.]]
+            a: ubyte; [[Alpha component.]]
          }
       }
 
       @property strikethrough_type {
-         [[Type of strikethrough style]]
+         [[Enables crossed-out text.]]
          values
          {
-            type: Efl.Text_Style_Strikethrough_Type; [[Strikethrough type]]
+            type: Efl.Text_Style_Strikethrough_Type; [[Strike-through type.]]
          }
       }
 
       @property strikethrough_color
       {
-         [[Color of strikethrough_style]]
+         [[Color of the line striking through the text.]]
          values
          {
-            r: ubyte; [[Red component]]
-            g: ubyte; [[Green component]]
-            b: ubyte; [[Blue component]]
-            a: ubyte; [[Alpha component]]
+            r: ubyte; [[Red component.]]
+            g: ubyte; [[Green component.]]
+            b: ubyte; [[Blue component.]]
+            a: ubyte; [[Alpha component.]]
          }
       }
 
       @property effect_type {
-         [[Type of effect used for the displayed text]]
+         [[Controls a number of decorations around the text, like shadow, outline
+           and glow, including combinations of them.]]
          values {
-            type: Efl.Text_Style_Effect_Type; [[Effect type]]
+            type: Efl.Text_Style_Effect_Type; [[Effect type.]]
          }
       }
       @property outline_color
       {
-         [[Color of outline effect]]
+         [[Color of the text outline.]]
          values
          {
-            r: ubyte; [[Red component]]
-            g: ubyte; [[Green component]]
-            b: ubyte; [[Blue component]]
-            a: ubyte; [[Alpha component]]
+            r: ubyte; [[Red component.]]
+            g: ubyte; [[Green component.]]
+            b: ubyte; [[Blue component.]]
+            a: ubyte; [[Alpha component.]]
          }
       }
 
       @property shadow_direction
       {
-         [[Direction of shadow effect]]
+         [[Direction of shadow effect.]]
          values
          {
-            type: Efl.Text_Style_Shadow_Direction; [[Shadow direction]]
+            type: Efl.Text_Style_Shadow_Direction; [[Shadow direction.]]
          }
       }
 
       @property shadow_color
       {
-         [[Color of shadow effect]]
+         [[Color of the shadow.]]
          values
          {
-            r: ubyte; [[Red component]]
-            g: ubyte; [[Green component]]
-            b: ubyte; [[Blue component]]
-            a: ubyte; [[Alpha component]]
+            r: ubyte; [[Red component.]]
+            g: ubyte; [[Green component.]]
+            b: ubyte; [[Blue component.]]
+            a: ubyte; [[Alpha component.]]
          }
       }
 
       @property glow_color
       {
-         [[Color of glow effect]]
+         [[Color of the glow decoration.]]
          values
          {
-            r: ubyte; [[Red component]]
-            g: ubyte; [[Green component]]
-            b: ubyte; [[Blue component]]
-            a: ubyte; [[Alpha component]]
+            r: ubyte; [[Red component.]]
+            g: ubyte; [[Green component.]]
+            b: ubyte; [[Blue component.]]
+            a: ubyte; [[Alpha component.]]
          }
       }
 
       @property glow2_color
       {
-         [[Second color of the glow effect]]
+         [[Color of the secondary glow decoration.
+           This is the color of the inner glow (where it touches the text) which
+           gradually fades into @.glow_color as it reaches the edge.
+         ]]
          values
          {
-            r: ubyte; [[Red component]]
-            g: ubyte; [[Green component]]
-            b: ubyte; [[Blue component]]
-            a: ubyte; [[Alpha component]]
+            r: ubyte; [[Red component.]]
+            g: ubyte; [[Green component.]]
+            b: ubyte; [[Blue component.]]
+            a: ubyte; [[Alpha component.]]
          }
       }
 
diff --git a/src/lib/evas/canvas/efl_canvas_textblock.eo b/src/lib/evas/canvas/efl_canvas_textblock.eo
index 7c6cf8e0e6..3b686918ee 100644
--- a/src/lib/evas/canvas/efl_canvas_textblock.eo
+++ b/src/lib/evas/canvas/efl_canvas_textblock.eo
@@ -6,7 +6,13 @@ class @beta Efl.Canvas.Textblock extends Efl.Canvas.Object implements Efl.Text,
                        Efl.Text_Markup, Efl.Ui.I18n
 {
    [[This is the Canvas-level text class. This class only takes care of rendering text,
-     if you need user interaction consider the classes in $Efl.Ui.]]
+     if you need user interaction consider the classes in $[Efl.Ui].
+
+     Note: No text will be rendered until a font, a font size and a font color are specified.
+     This can be accomplished using @Efl.Text_Font.font_family, @Efl.Text_Font.font_size and
+     @Efl.Text_Style.normal_color.
+     Alternatively, @.style_apply can be used providing the attributes $font, $font_size and $color.
+   ]]
    methods {
       @property is_empty {
          [[Whether the object is empty (no text) or not.
@@ -80,337 +86,265 @@ class @beta Efl.Canvas.Textblock extends Efl.Canvas.Object implements Efl.Text,
          }
       }
       style_apply {
-         [[Applies a style to the text object. Applied style attributes override old ones, leaving other attributes
-         unaffected.
-         This is similar to setting individual style attributes using properties like @Efl.Text_Font.font_slant or
-         @Efl.Text_Format.wrap.
-
-         The style can be set as "attribute"="Value".
-         Multible attribute can be set at once separated by space.
-
-         The following styling attributes are accepted:
-
-         - Font
-         - Font fallback
-         - Font size
-         - Font source
-         - Font weight
-         - Font style
-         - Font width
-         - Language
-         - Color
-         - Underline Color
-         - Second Underline Color
-         - Underline Dash Color
-         - Outline Color
-         - Shadow Color
-         - First Glow Color
-         - Second Glow Color
-         - Backing Color
-         - Strikethrough Color
-         - Horizontal Align
-         - Vertical Align
-         - Wrap
-         - Left margin
-         - Right margin
-         - Underline
-         - Strikethrough
-         - Backing
-         - Style
-         - Tabstops
-         - Line size
-         - Relative line size
-         - Line gap
-         - Relative line gap
-         - Item
-         - Line fill
-         - Ellipsis
-         - Password
-         - Underline dash width
-         - Underline dash gap
-         - Underline height
-
-         Font
-         This sets the name of the font to be used.
-         font=<font name>
-
-         Font fallback
-         A comma delimited list of fonts to try if finding the primary font fails.
-         font_fallbacks=<font names>
-
-         Font size
-         This sets the the size of font in points to be used.
-         font_size=<size>
-
-         Font source
-         Specify source from which to search for the font.
-         font_source=<source>
-
-         Font weight
-         Sets the weight of the font. The value must be one of:
-         "normal"
-         "thin"
-         "ultralight"
-         "extralight"
-         "light"
-         "book"
-         "medium"
-         "semibold"
-         "bold"
-         "ultrabold"
-         "extrabold"
-         "black"
-         "extrablack"
-         font_weight=<weight>
-
-         Font style
-         Sets the style of the font. The value must be one of:
-         "normal"
-         "oblique"
-         "italic"
-         font_style=<style>
-
-         Font width
-         Sets the width of the font. The value must be one of:
-         "normal"
-         "ultracondensed"
-         "extracondensed"
-         "condensed"
-         "semicondensed"
-         "semiexpanded"
-         "expanded"
-         "extraexpanded"
-         "ultraexpanded"
-         font_width=<width>
-
-         Language
-         Overrides the language defined in font. For example, lang=he.
-         The value can either be a language text or one of presets:
-         "auto" - Respects system locale settings as language
-         "none" - Disable language support
-         lang=<language>
-
-         Color Commands <color>:
-         The following formats are accepted:
-         "#RRGGBB"
-         "#RRGGBBAA"
-         "#RGB"
-         "#RGBA"
-         "rgb(r,g,b)"
-         "rgba(r,g,b,a)"
-         "color_name" like "red" (X11 color names)
-
-         Color
-         Sets the color of the text.
-         color=<color>
-
-         Underline Color
-         Sets the color of the underline.
-         underline_color=<color>
-
-         Second Underline Color
-         Sets the color of the second line of underline(when using underline mode "double").
-         underline2_color=<color>
-
-         Underline Dash Color
-         Sets the color of dashed underline.
-         underline_dash_color=<color>
-
-         Outline Color
-         Sets the color of the outline of the text.
-         outline_color=<color>
-
-         Shadow Color
-         Sets the color of the shadow of the text.
-         shadow_color=<color>
-
-         First Glow Color
-         Sets the first color of the glow of text.
-         glow_color=<color>
-
-         Second Glow Color
-         Sets the second color of the glow of text.
-         glow2_color=<color>
-
-         Backing Color
-         Sets a background color for text.
-         backing_color=<color>
-
-         Strikethrough Color
-         Sets the color of text that is striked through.
-         strikethrough_color=<color>
-
-         Horizontal Align
-         Sets the horizontal alignment of the text. The value can either be a number, a percentage or one of several presets:
-         "auto" - Respects LTR/RTL settings
-         "locale" - Respects locale(language) direction settings
-         "center" - Centers the text in the line
-         "middle" - Alias for "center"
-         "left" - Puts the text at the left of the line
-         "right" - Puts the text at the right of the line
-         "start" - Respects LTR/RTL settings. It is same with "auto"
-         "end" - Puts the text at the opposite side of LTR/RTL settings
-         <number> - A number between 0.0 and 1.0 where 0.0 represents "left" and 1.0 represents "right"
-         <number>% - A percentage between 0% and 100% where 0% represents "left" and 100% represents "right"
-         align=<value or preset>
-
-         Vertical Align
-         Sets the vertical alignment of the text.
-         The value can either be a number or one of the following presets:
-         "top" - Puts text at the top of the line
-         "center" - Centers the text in the line
-         "middle" - Alias for "center"
-         "bottom" - Puts the text at the bottom of the line
-         "baseline" - Baseline
-         "base" - Alias for "baseline"
-         <number> - A number between 0.0 and 1.0 where 0.0 represents "top" and 1.0 represents "bottom"
-         <number>% - A percentage between 0% and 100% where 0% represents "top" and 100% represents "bottom"
-         valign=<value or preset>
-         See explanation of baseline at: https://en.wikipedia.org/wiki/Baseline_%28typography%29
-
-         Wrap
-         Sets the wrap policy of the text. The value must be one of the following:
-         "word" - Only wraps lines at word boundaries
-         "char" - Wraps at any character
-         "mixed" - Wrap at words if possible, if not at any character
-         "hyphenation" - Hyphenate if possible, if not wrap at words if possible, if not at any character
-         "none" - Don't wrap, this is the default value
-         wrap=<value or preset>
-
-         Left margin
-         Sets the left margin of the text (in pixel). The value can be a number, an increment, decrement or "reset":
-         +<number> - Increments existing left margin by <number>
-         -<number> - Decrements existing left margin by <number>
-         <number> - Sets left margin to <number>
-         "reset" - Sets left margin to 0
-         left_margin=<value or reset>
-
-         Right margin
-         Sets the right margin of the text (in pixel). The value can be a number, an increment, decrement or "reset":
-         +<number> - Increments existing right margin by <number>
-         -<number> - Decrements existing right margin by <number>
-         <number> - Sets left margin to <number>
-         "reset" - Sets left margin to 0
-         right_margin=<value or reset>
-
-         Underline
-         Sets if and how a text will be underlined. The value must be one of the following:
-         "off" - No underlining
-         "single" - A single line under the text
-         "on" - Alias for "single"
-         "double" - Two lines under the text
-         "dashed" - A dashed line under the text
-         underline=off/single/on/double/dashed
-
-         Strikethrough
-         Sets if the text will be striked through. The value must be one of the following:
-         "off" - No strikethrough
-         "on" - Strikethrough
-         strikethrough=on/off
-
-         Backing
-         Sets if the text will have background color enabled or disabled. The value must be one of the following:
-         "off" - No backing
-         "on" - Backing
-         backing=on/off
-
-         Style
-         Sets the style of the text. The value must be a string composed of two comma separated parts.
-         The first part of the value sets the appearance of the text, the second the position.
-         The first part may be any of the following values:
-         "plain"
-         "off" - Alias for "plain"
-         "none" - Alias for "plain"
-         "shadow"
-         "outline"
-         "soft_outline"
-         "outline_shadow"
-         "outline_soft_shadow"
-         "glow"
-         "far_shadow"
-         "soft_shadow"
-         "far_soft_shadow" The second part may be any of the following values:
-         "bottom_right"
-         "bottom"
-         "bottom_left"
-         "left"
-         "top_left"
-         "top"
-         "top_right"
-         "right"
-         style=<appearance>,<position>
-
-         Tabstops
-         Sets the size (in pixel) of the tab character. The value must be a number greater than one.
-         tabstops=<number>
-
-         Line size
-         Sets the size (in pixel) of line of text. The value should be a number.
-         Setting this value sets linerelsize to 0%!
-         linesize=<number>
-
-         Relative line size
-         Percentage indicating the wanted size of the line relative to the calculated size.
-         Setting this value sets linesize to 0!
-         linerelsize=<number>%
-
-         Line gap
-         Sets the size (in pixel) of the line gap in text (distance between lines). The value should be a number.
-         Setting this value sets linerelgap to 0%!
-         linegap=<number>
-
-         Relative line gap
-         Sets the relative size of the line gap in text based calculated size. The value must be a percentage.
-         Setting this value sets linegap to 0!
-         linerelgap=<number>%
-
-         Line fill
-         Sets the size of the line fill in text. The value must be a percentage (how much line fill its canvas).
-         For example setting value to 100%, means the one line will fill it canvas.
-         linefill=<number>%
-
-         Ellipsis
-         Sets ellipsis mode. The value should be a number.
-         Any value smaller than 0.0 or greater than 1.0 disables ellipsis.
-         A value of 0 means ellipsizing the leftmost portion of the text first, 1 on the other hand the rightmost portion.
-         ellipsis=<number>
-
-         Password
-         Sets if the text is being used for passwords.
-         Enabling this causes all characters to be substituted for '*'. Value must be one of the following:
-         "on" - Enable
-         "off" - Disable
-         password=on/off
-
-         Underline dash width
-         Sets the width of the underline dash (in pixel). The value should be a number.
-         underline_dash_width=<number>
-
-         Underline dash gap
-         Sets the gap of the underline dash (in pixel). The value should be a number.
-         underline_dash_gap=<number>
-
-         Underline height
-         Sets the height of the single underline (in pixel). The value should be a floating number.
-         underline_height=<floatingnumber>
-
-         Gfx Filter
-         Experimental filter, see efl_gfx_filter for more information.
-         gfx_filter='filter name'
+         [[Applies several style attributes at once using a formatting string.
+           Given style attributes override previous values, leaving other attributes unaffected.
+           This is akin to setting individual style attributes using properties like
+           @Efl.Text_Font.font_slant or @Efl.Text_Format.wrap, for example.
+
+           The formatting string is a whitespace-separated list of $[attribute=value] pairs.
+
+           The following attributes are accepted:
+
+           - $font: Name of the font to use.
+             Default value is empty, meaning that no text will be rendered.
+             Requires $font_size and $font_color.
+             See @Efl.Text_Font.font_family.
+
+           - $font_fallbacks: Comma-delimited list of fonts to try if finding the primary font fails.
+             Example: $[font_fallbacks=consolas,courier,monospace].
+             Default value is empty.
+             See @Efl.Text_Font.font_fallbacks.
+
+           - $font_size: Height of font, in points.
+             Default value is 0.
+             Requires $font and $font_color.
+             See @Efl.Text_Font.font_size.
+
+           - $font_source: Path to the file containing the font to use.
+             Example: $[font_source=/usr/share/fonts/Sans.ttf].
+             Default value is empty.
+             See @Efl.Text_Font.font_source.
+
+           - $font_weight: Thickness of the font. The value must be one of: $normal, $thin, $ultralight, $extralight,
+             $light, $book, $medium, $semibold, $bold, $ultrabold, $extrabold, $black and $extrablack.
+             Default value is $normal.
+             See @Efl.Text_Font.font_weight.
+
+           - $font_style: Style of the font. The value must be one of: $normal, $oblique and $italic.
+             Default value is $normal.
+             See @Efl.Text_Font.font_slant.
+
+           - $font_width: How wide the font is, relative to its height. The value must be one of:
+             $normal, $ultracondensed, $extracondensed, $condensed, $semicondensed, $semiexpanded, $expanded,
+             $extraexpanded and $ultraexpanded.
+             Default value is $normal.
+             See @Efl.Text_Font.font_weight.
+
+           - $lang: A 2-letter ISO 639-1 language code, $auto (to use the system locale setting) or $none (to disable
+             language support).
+             Example: $[lang=he].
+             Default value is empty.
+             See @Efl.Text_Font.font_lang.
+
+           - $color: Color code for the text (See bottom for the complete list of supported codes).
+             Default value is $[rgba(0,0,0,0)] meaning that no text will be rendered.
+             Requires $font and $font_size.
+             See @Efl.Text_Style.normal_color.
+
+           - $underline_color: Color code for the text underline (See bottom for the complete list of supported codes).
+             Default value is $[rgba(0,0,0,0)] meaning that no underline will be rendered.
+             Requires $underline.
+             See @Efl.Text_Style.underline_color.
+
+           - $underline2_color: Color code for the secondary text underline (See bottom for the complete list of
+             supported codes). Only valid when $[underline=double].
+             Default value is $[rgba(0,0,0,0)] meaning that secondary underline will not be rendered.
+             See @Efl.Text_Style.underline2_color.
+
+           - $underline_dash_color: Color code for the dashed underline (See bottom for the complete list of supported
+             codes). Only valid when $[underline=dashed].
+             Default value is $[rgba(0,0,0,0)] meaning that dashed underline will not be rendered.
+             See @Efl.Text_Style.underline_dashed_color.
+
+           - $outline_color: Color code for the text outline (See bottom for the complete list of supported codes).
+             Only valid when the $style attribute includes an outline.
+             Default value is $[rgba(0,0,0,0)] meaning that no outline will be rendered.
+             See @Efl.Text_Style.outline_color.
+
+           - $shadow_color: Color code for the text shadow (See bottom for the complete list of supported codes).
+             Only valid when the $style attribute includes a shadow.
+             Default value is $[rgba(0,0,0,0)] meaning that no shadow will be rendered.
+             See @Efl.Text_Style.shadow_color.
+
+           - $glow_color: Color code for the glow component of the text (See bottom for the complete list of supported
+             codes). Only valid when the $style attribute includes a glow.
+             Default value is $[rgba(0,0,0,0)] meaning that no glow will be rendered.
+             See @Efl.Text_Style.glow_color.
+
+           - $glow2_color: Color code for the secondary (inner) glow component of the text (See bottom for the complete
+             list of supported codes). Only valid when the $style attribute includes a glow.
+             Default value is $[rgba(0,0,0,0)] meaning that only the primary $glow_color will be used.
+             See @Efl.Text_Style.glow2_color.
+
+           - $backing_color: Color code for the background of the text (See bottom for the complete list of supported
+             codes). Use a fully transparent color to disable the background.
+             Default value is $[rgba(0,0,0,0)] meaning that no backing will be rendered.
+             Requires $backing.
+             See @Efl.Text_Style.backing_color.
+
+           - $strikethrough_color: Color code for the line striking through the text (See bottom for the complete list
+             of supported codes). Only valid when $[strikethrough=on]
+             Default value is $[rgba(0,0,0,0)] meaning that no strike-through line will be rendered.
+             See @Efl.Text_Style.strikethrough_color.
+
+           - $align: Horizontal alignment of the text. The value can either be a decimal number ($[0.0] means "left"
+             and $[1.0] means "right"), a percentage ($[0%] means "left" and $[100%] means "right") or one of:
+             $auto (Respects LTR/RTL settings), $locale (Respects language direction settings), $center
+             (Centers the text in the line), $middle (Alias for $center), $left (Puts the text at the left of the line),
+             $right (Puts the text at the right of the line), $start (Alias for $auto), $end (Puts the text at the
+             opposite side of LTR/RTL settings).
+             Default value is $auto.
+             See @Efl.Text_Format.horizontal_align.
+
+           - $valign: Vertical alignment of the text. The value can either be a decimal number ($[0.0] means "top"
+             and $[1.0] means "bottom"), a percentage ($[0%] means "top" and $[100%] means "bottom") or one of:
+             $top (Puts the text at the top of the text box), $center (Puts the text at the middle of the text box),
+             $middle (Alias for $center), $bottom (Puts the text at the bottom of the text box),
+             $baseline (Puts the text's baseline at the middle of the text box), $base (Alias for $baseline).
+             Default value is $baseline.
+             See @Efl.Text_Format.vertical_align.
+
+           - $wrap: Wrapping policy of the text. The value must be one of the following: $word (Only wraps lines at
+             word boundaries), $char (Wraps at any character), $mixed (Wraps at word boundaries if possible,
+             at any character if not), $hyphenation (Hyphenate if possible, otherwise try wrapping at word boundaries
+             or at any character) or $none to disable wrapping.
+             Default value is $none.
+             See @Efl.Text_Format.wrap.
+
+           - $left_margin: Distance in pixels from the left side of the text block to the beginning of the text
+             (inner margin). The value can be a number (to set the margin), or a number preceded by $[+] or $[-]
+             to increment or decrement the existing margin value. $reset is also accepted, to set the margin to
+             0 pixels.
+             Default value is $[0].
+             Examples: $[left_margin=10], $[left_margin=+10], $[left_margin=reset].
+
+           - $right_margin: Distance in pixels from the right side of the text block to the beginning of the text
+             (inner margin). The value can be a number (to set the margin), or a number preceded by $[+] or $[-]
+             to increment or decrement the existing margin value. $reset is also accepted, to set the margin to
+             0 pixels.
+             Default value is $[0].
+             Examples: $[right_margin=10], $[right_margin=+10], $[right_margin=reset].
+
+           - $underline: Style of the underline. The value must be one of $off (No underlining),
+             $single (A single line under the text), $on (Alias for $single), $double (Two lines under the text),
+             $dashed (A dashed line under the text).
+             Default value is $off.
+             Requires either $underline_color, $underline2_color or $underline_dash_color.
+             See @Efl.Text_Style.underline_type.
+
+           - $strikethrough: Enables crossed-out text. Possible values are $on and $off.
+             Default value is $off.
+             Requires $strikethrough_color.
+             See @Efl.Text_Style.strikethrough_type.
+
+           - $backing: Enables background color for the text. Possible values are $on and $off.
+             Default value is $off.
+             Requires $backing_color.
+             See @Efl.Text_Style.backing_type.
+
+           - $style: Controls a number of decorations around the text, like shadow, outline and glow, including
+             combinations of them. Possible values are $plain (No decoration, alias for $off and $none),
+             $shadow, $outline, $soft_outline, $outline_shadow, $outline_soft_shadow, $glow (alias for $soft_outline),
+             $far_shadow, $soft_shadow and $far_soft_shadow.
+             All values involving a shadow accept a second parameter, separated by a comma, to indicate the shadow
+             direction. Valid positions are $bottom_right, $bottom, $bottom_left, $left, $top_left, $top, $top_right
+             and $right.
+             Default value is $plain.
+             Requires either $shadow_color, $glow_color or $outline_color.
+             Examples: $[style=outline], $[style=shadow,bottom_right], $[style=outline_shadow,bottom].
+             See @Efl.Text_Style.effect_type and @Efl.Text_Style.shadow_direction.
+
+           - $tabstops: Size (in pixels) of the tab character. The value must be a number greater than one.
+             Default value is $[32].
+             See @Efl.Text_Format.tabstops.
+
+           - $linesize: Distance (in pixels) from the baseline of one line of text to the next. This is, a value of
+             $[0] would render all lines on top of each other (However, this value will be ignored if it results in
+             overlapping lines of text).
+             Setting this value sets $linerelsize to $[0%] (disables it).
+             Default value is $[0].
+
+           - $linerelsize: Distance (in percentage over the natural line height) from the baseline of one line of
+             text to the next. A value of $[100%] does not have any impact, smaller values render lines closer together
+             and bigger values render them further apart.
+             Setting this value sets $linesize to $[0] (disables it).
+             Default value is $[0%].
+
+           - $linegap: Additional empty space (in pixels) between the bottom of one line of text and the top of the
+             next. Setting this value sets $linerelgap to $[0%] (disables it).
+             Default value is $[0].
+             See @Efl.Text_Format.linegap.
+
+           - $linerelgap: Additional empty space (in percentage over the natural line height) between the bottom of
+             one line of text and the top of the next.
+             Setting this value sets $linegap to $[0] (disables it).
+             Default value is $[0%].
+             See @Efl.Text_Format.linerelgap.
+
+           - $linefill: An alternate way to specify the $linesize as a percentage of the canvas height.
+             A value of $[100%] means that a single line fills the canvas, whereas $[25%] means that 4 lines
+             fit in the same height.
+             When both $linefill and $linesize are specified the one resulting in the smallest line size is used.
+             Default value is $[0].
+
+           - $ellipsis: Controls automatic addition of ellipsis "..." to replace text which cannot be shown.
+             The value must be a number indicating the position of the ellipsis inside the visible text.
+             $[0.0] means the beginning of the text, $[1.0] means the end of the text, and values in between
+             mean the proportional position inside the text.
+             Any value smaller than 0 or greater than 1 disables ellipsis.
+             Default value is $[-1].
+             Examples: $[ellipsis=0.5
+             See @Efl.Text_Format.ellipsis.
+
+           - $password: Enabling this causes all characters to be replaced by $replacement_char.
+             This is useful for password input boxes.
+             Value must be either $on or $off.
+             Default value is $[off].
+             Requires $replacement_char.
+             See @Efl.Text_Format.password.
+
+           - $replacement_char: Character to use instead of the actual characters when $password is $on.
+             Default value is empty, meaning that no replacement will take place.
+             Requires $password.
+             Examples: $[replacement_char=*].
+             See @Efl.Text_Format.replacement_char.
+
+           - $underline_dash_width: Length (in pixels) of the dashes when $underline is $dashed.
+             Default value is $[6].
+             See @Efl.Text_Style.underline_dashed_width.
+
+           - $underline_dash_gap: Length (in pixels) of the gaps between the dashes when $underline is $dashed.
+             Default value is $[2].
+             See @Efl.Text_Style.underline_dashed_gap.
+
+           - $underline_height: Width (in pixels) of the single underline when $underline is $single.
+             Default value is $[1].
+             See @Efl.Text_Style.underline_height.
+
+           - $gfx_filter: Experimental filter name. See @Efl.Gfx.Filter for more information.
+
+           Color codes: Colors can be specified using any of the following formats:
+           $[#RRGGBB], $[#RRGGBBAA], $[#RGB], $[#RGBA], $[rgb(r,g,b)], $[rgba(r,g,b,a)].
+           Additionally, X11 color names like $red or $blanchedalmond can be used.
+           See https://en.wikipedia.org/wiki/X11_color_names for the full list.
          ]]
 
          params {
-            @in style: string; [[A whitespace-separated list of $[property=value] pairs, for example, $[font=sans font_size=30].]]
+            @in style: string; [[A whitespace-separated list of $[attribute=value] pairs, for example,
+                                 $[font=sans font_size=30 color=white].]]
          }
       }
       @property all_styles {
-         [[A string representing the complete set of styles applied to this text object.
+         [[A string representing the complete set of attributes applied to this text object.
            This includes the default attributes plus any additional style applied with @.style_apply
-           or individual style properties like @Efl.Text_Font.font_slant or @Efl.Text_Format.wrap.]]
+           or individual style properties like @Efl.Text_Font.font_slant or @Efl.Text_Format.wrap.
+
+           See @.style_apply for the description of all attributes.
+         ]]
          get {}
          values {
-            style: string; [[A whitespace-separated list of $[property=value] pairs, for example,
-                                 $[font=sans size=30]. Do not free.]]
+            style: string; [[A whitespace-separated list of $[attribute=value] pairs, for example,
+                             $[font=sans font_size=30 color=white].]]
          }
       }
       @property size_formatted {