slideshow: convert docs

1 files changed, 197 insertions, 313 deletions

diff --git a/src/lib/elm_slideshow.eo b/src/lib/elm_slideshow.eo
index d113b1c0b..8e0f91448 100644
--- a/src/lib/elm_slideshow.eo
+++ b/src/lib/elm_slideshow.eo
@@ -4,412 +4,296 @@ class Elm.Slideshow (Elm.Layout, Elm_Interface_Atspi_Widget_Action)
    methods {
       @property cache_after {
          set {
-            /*@
-            Set the number of items to cache, on a given slideshow widget,
-            <b>after the current item</b>
+            [[Set the number of items to cache, on a given slideshow widget,
+              after the current item.
 
-            The default value for this property is $2. See
-            @ref Slideshow_Caching "slideshow caching" for more details.
-
-            @see elm_slideshow_cache_after_get()
-
-            @ingroup Slideshow */
+              The default value for this property is 2. See
+              \@ref Slideshow_Caching "slideshow caching" for more details.
+            ]]
          }
          get {
-            /*@
-            Get the number of items to cache, on a given slideshow widget,
-            <b>after the current item</b>
-
-            @return The number of items set to be cached after the current one
-
-            @see elm_slideshow_cache_after_set() for more details
-
-            @ingroup Slideshow */
+            [[Get the number of items to cache, on a given slideshow widget,
+              after the current item.
+            ]]
          }
          values {
-            count: int; /*@ Number of items to cache after the current one */
+            count: int; [[Number of items to cache after the current one.]]
          }
       }
       @property cache_before {
          set {
-            /*@
-            Set the number of items to cache, on a given slideshow widget,
-            <b>before the current item</b>
+            [[Set the number of items to cache, on a given slideshow widget,
+              before the current item.
 
-            The default value for this property is $2. See
-            @ref Slideshow_Caching "slideshow caching" for more details.
-
-            @see elm_slideshow_cache_before_get()
-
-            @ingroup Slideshow */
+              The default value for this property is 2. See
+              \@ref Slideshow_Caching "slideshow caching" for more details.
+            ]]
          }
          get {
-            /*@
-            Get the number of items to cache, on a given slideshow widget,
-            <b>before the current item</b>
-
-            @return The number of items set to be cached before the current one
-
-            @see elm_slideshow_cache_before_set() for more details
-
-            @ingroup Slideshow */
+            [[Get the number of items to cache, on a given slideshow widget,
+              before the current item.
+            ]]
          }
          values {
-            count: int; /*@ Number of items to cache before the current one */
+            count: int; [[Number of items to cache before the current one.]]
          }
       }
       @property layout {
          set {
-            /*@
-            Set the current slide layout in use for a given slideshow widget
-
-            If $layout is implemented in $obj's theme (i.e., is contained
-            in the list returned by elm_slideshow_layouts_get()), this new
-            images layout will be used on the widget.
+            [[Set the current slide layout in use for a given slideshow widget
 
-            @see elm_slideshow_layouts_get() for more details
+              If $layout is implemented in $obj's theme (i.e., is contained
+              in the list returned by elm_slideshow_layouts_get()), this new
+              images layout will be used on the widget.
 
-            @ingroup Slideshow */
+              See @.layouts.get for more details.
+            ]]
          }
          get {
-            /*@
-            Get the current slide layout in use for a given slideshow widget
-
-            @return The current layout's name
-
-            @see elm_slideshow_layout_set() for more details
-
-            @ingroup Slideshow */
+            [[Get the current slide layout in use for a given slideshow widget.]]
          }
          values {
-            layout: const(char)*; /*@ The new layout's name string */
+            layout: const(char)*; [[The new layout's name string.]]
          }
       }
       @property transition {
          set {
-            /*@
-            Set the current slide transition/effect in use for a given
-            slideshow widget
+            [[Set the current slide transition/effect in use for a given
+              slideshow widget.
 
-            If $transition is implemented in $obj's theme (i.e., is
-            contained in the list returned by
-            elm_slideshow_transitions_get()), this new sliding effect will
-            be used on the widget.
-
-            @see elm_slideshow_transitions_get() for more details
-
-            @ingroup Slideshow */
+              If $transition is implemented in $obj's theme (i.e., is
+              contained in the list returned by @.transitions.get), this
+              new sliding effect will be used on the widget.
+            ]]
          }
          get {
-            /*@
-            Get the current slide transition/effect in use for a given
-            slideshow widget
-
-            @return The current transition's name
-
-            @see elm_slideshow_transition_set() for more details
-
-            @ingroup Slideshow */
+            [[Get the current slide transition/effect in use for a given
+              slideshow widget.
+            ]]
          }
          values {
-            transition: const(char)* @nullable; /*@ The new transition's name string */
+            transition: const(char)* @nullable; [[The new transition's name string.]]
          }
       }
       @property loop {
          set {
-            /*@
-            Set if, after a slideshow is started, for a given slideshow
-            widget, its items should be displayed cyclically or not.
-
-            @note elm_slideshow_next() and elm_slideshow_previous() will @b
-            ignore what is set by this functions, i.e., they'll @b always
-            cycle through items. This affects only the "automatic"
-            slideshow, as set by elm_slideshow_timeout_set().
-
-            @see elm_slideshow_loop_get()
+            [[Set if, after a slideshow is started, for a given slideshow
+              widget, its items should be displayed cyclically or not.
 
-            @ingroup Slideshow */
+              Note: @.next and @.previous will ignore what is set by this
+              functions, i.e., they'll always cycle through items. This
+              affects only the "automatic" slideshow, as set by @.timeout.set.
+            ]]
          }
          get {
-            /*@
-            Get if, after a slideshow is started, for a given slideshow
-            widget, its items are to be displayed cyclically or not.
-
-            @return $true, if the items in $obj will be cycled
-            through or $false, otherwise
-
-            @see elm_slideshow_loop_set() for more details
-
-            @ingroup Slideshow */
+            [[Get if, after a slideshow is started, for a given slideshow
+              widget, its items are to be displayed cyclically or not.
+            ]]
          }
          values {
-            loop: bool; /*@ Use $true to make it cycle through items or
-            $false for it to stop at the end of $obj's internal
-            list of items */
+            loop: bool; [[Use $true to make it cycle through items or
+                          $false for it to stop at the end of $obj's
+                          internal list of items.]]
          }
       }
       @property timeout {
          set {
-            /*@
-            Set the interval between each image transition on a given
-            slideshow widget, <b>and start the slideshow, itself</b>
-
-            After this call, the slideshow widget will start cycling its
-            view, sequentially and automatically, with the images of the
-            items it has. The time between each new image displayed is going
-            to be $timeout, in @b seconds. If a different timeout was set
-            previously and an slideshow was in progress, it will continue
-            with the new time between transitions, after this call.
-
-            @note A value less than or equal to 0 on $timeout will disable
-            the widget's internal timer, thus halting any slideshow which
-            could be happening on $obj.
-
-            @see elm_slideshow_timeout_get()
-
-            @ingroup Slideshow */
+            [[Set the interval between each image transition on a given
+              slideshow widget and start the slideshow itself.
+
+              After this call, the slideshow widget will start cycling its
+              view, sequentially and automatically, with the images of the
+              items it has. The time between each new image displayed is
+              going to be $timeout, in seconds. If a different timeout was
+              set previously and an slideshow was in progress, it will
+              continue with the new time between transitions, after this call.
+
+              Note: A value less than or equal to 0 on $timeout will disable
+              the widget's internal timer, thus halting any slideshow which
+              could be happening on $obj.
+            ]]
          }
          get {
-            /*@
-            Get the interval set for image transitions on a given slideshow
-            widget.
-
-            @return Returns the timeout set on it or -1.0, on errors
-
-            @see elm_slideshow_timeout_set() for more details
-
-            @ingroup Slideshow */
+            [[Get the interval set for image transitions on a given
+              slideshow widget.
+            ]]
          }
          values {
-            timeout: double; /*@ The new displaying timeout for images */
+            timeout: double; [[The new displaying timeout for images.]]
          }
       }
       @property items {
          get {
-            /*@
-            Get the internal list of items in a given slideshow widget.
-
-            @return The list of items (#Elm.Widget_Item as data) or
-            $NULL on errors.
-
-            This list is @b not to be modified in any way and must not be
-            freed. Use the list members with functions like
-            elm_object_item_del(), elm_object_item_data_get().
-
-            @warning This list is only valid until $obj object's internal
-            items list is changed. It should be fetched again with another
-            call to this function when changes happen.
-
-            @ingroup Slideshow */
-            return: const(list<Elm.Widget_Item *>)*;
+            [[Get the internal list of items in a given slideshow widget.
+
+              This list is not to be modified in any way and must not be
+              freed.
+
+              Warning: This list is only valid until $obj object's internal
+              items list is changed. It should be fetched again with another
+              call to this function when changes happen.
+            ]]
+            return: const(list<Elm.Widget_Item *>)*; [[
+               The list of items (#Elm.Widget_Item as data) or $null on
+               errors.
+            ]]
          }
       }
       @property transitions {
          get {
-            /*@
-            Returns the list of sliding transition/effect names available, for a
-            given slideshow widget.
-
-            @return The list of transitions (list of @b stringshared strings
-            as data)
-
-            The transitions, which come from $obj's theme, must be an EDC
-            data item named $"transitions" on the theme file, with (prefix)
-            names of EDC programs actually implementing them.
-
-            The available transitions for slideshows on the default theme are:
-            - $"fade" - the current item fades out, while the new one
-            fades in to the slideshow's viewport.
-            - $"black_fade" - the current item fades to black, and just
-            then, the new item will fade in.
-            - $"horizontal" - the current item slides horizontally, until
-            it gets out of the slideshow's viewport, while the new item
-            comes from the left to take its place.
-            - $"vertical" - the current item slides vertically, until it
-            gets out of the slideshow's viewport, while the new item comes
-            from the bottom to take its place.
-            - $"square" - the new item starts to appear from the middle of
-            the current one, but with a tiny size, growing until its
-            target (full) size and covering the old one.
-
-            @warning The stringshared strings get no new references
-            exclusive to the user grabbing the list, here, so if you'd like
-            to use them out of this call's context, you'd better @c
-            eina_stringshare_ref() them. Also the list is an internal list and
-            so is only valid for as long as the slideshow object is valid and
-            has not internally changed its list for some reason, so make a
-            copy if you need it around.
-
-            @see elm_slideshow_transition_set()
-
-            @ingroup Slideshow */
-            return: const(list<const(char)*>)*;
+            [[Returns the list of sliding transition/effect names available,
+              for a given slideshow widget.
+
+              The transitions, which come from $obj's theme, must be an EDC
+              data item named $"transitions" on the theme file, with (prefix)
+              names of EDC programs actually implementing them.
+
+              The available transitions for slideshows on the default theme
+              are "fade" (the current item fades out, while the new one
+              fades in to the slideshow's viewport), "black_fade" (the
+              current item fades to black, and just then, the new item
+              will fade in), "horizontal" (the current item slides
+              horizontally, until it gets out of the slideshow's viewport,
+              while the new item comes from the left to take its place),
+              "vertical" (the current item slides vertically, until it
+              gets out of the slideshow's viewport, while the new item
+              comes from the bottom to take its place), "square" (the
+              new item starts to appear from the middle of the current
+              one, but with a tiny size, growing until its target (full)
+              size and covering the old one.
+
+              Warning: The stringshared strings get no new references
+              exclusive to the user grabbing the list, here, so if you'd
+              like to use them out of this call's context, you'd better
+              \@ref eina_stringshare_ref them. Also the list is an internal
+              list and so is only valid for as long as the slideshow object
+              is valid and has not internally changed its list for some
+              reason, so make a copy if you need it around.
+            ]]
+            return: const(list<const(char)*>)*; [[
+               The list of transitions (list of stringshared strings
+               as data).
+            ]]
          }
       }
       @property count {
          get {
-            /*@
-            Get the number of items stored in a given slideshow widget
-
-            @return The number of items on $obj, at the moment of this call
-
-            @ingroup Slideshow */
-            return: uint;
+            [[Get the number of items stored in a given slideshow widget.]]
+            return: uint; [[The number of items on $obj, at the moment of this call.]]
          }
       }
       @property item_current {
          get {
-            /*@
-            Returns the currently displayed item, in a given slideshow widget
-
-            @return A handle to the item being displayed in $obj or
-            $NULL, if none is (and on errors)
-
-            @ingroup Slideshow */
-            return: Elm.Widget_Item *;
+            [[Returns the currently displayed item, in a given slideshow widget.]]
+            return: Elm.Widget_Item *; [[A handle to the item being displayed
+                                         in $obj or $null, if none is (and
+                                         on errors)]]
          }
       }
       @property layouts {
          get {
-            /*@
-            Returns the list of @b layout names available, for a given
-            slideshow widget.
-
-            @return The list of layouts (list of @b stringshared strings
-            as data)
-
-            Slideshow layouts will change how the widget is to dispose each
-            image item in its viewport, with regard to cropping, scaling,
-            etc.
-
-            The layouts, which come from $obj's theme, must be an EDC
-            data item name $"layouts" on the theme file, with (prefix)
-            names of EDC programs actually implementing them.
-
-            The available layouts for slideshows on the default theme are:
-            - $"fullscreen" - item images with original aspect, scaled to
-            touch top and down slideshow borders or, if the image's height
-            is not enough, left and right slideshow borders.
-            - $"not_fullscreen" - the same behavior as the $"fullscreen"
-            one, but always leaving 10% of the slideshow's dimensions of
-            distance between the item image's borders and the slideshow
-            borders, for each axis.
-
-            @warning The stringshared strings get no new references
-            exclusive to the user grabbing the list, here, so if you'd like
-            to use them out of this call's context, you'd better @c
-            eina_stringshare_ref() them.
-
-            @see elm_slideshow_layout_set()
-
-            @ingroup Slideshow */
-            return: const(list<const(char)*>)*;
+            [[Returns the list of layout names available, for a given
+              slideshow widget.
+
+              Slideshow layouts will change how the widget is to dispose
+              each image item in its viewport, with regard to cropping,
+              scaling, etc.
+
+              The layouts, which come from $obj's theme, must be an EDC
+              data item name $"layouts" on the theme file, with (prefix)
+              names of EDC programs actually implementing them.
+
+              The available layouts for slideshows on the default theme are
+              "fullscreen" (item images with original aspect, scaled to
+              touch top and down slideshow borders or, if the image's height
+              is not enough, left and right slideshow borders) and
+              "not_fullscreen" (the same behavior as the "fullscreen"
+              one, but always leaving 10% of the slideshow's dimensions of
+              distance between the item image's borders and the slideshow
+              borders, for each axis)-
+
+              Warning: The stringshared strings get no new references
+              exclusive to the user grabbing the list, here, so if you'd
+              like to use them out of this call's context, you'd better
+              \@ref eina_stringshare_ref them.
+            ]]
+            return: const(list<const(char)*>)*; [[
+               The list of layouts (list of stringshared strings as data)
+            ]]
          }
       }
       previous {
-         /*@
-         Slide to the @b previous item, in a given slideshow widget
-
-         The sliding animation $obj is set to use will be the
-         transition effect used, after this call is issued.
-
-         @note If the beginning of the slideshow's internal list of items
-         is reached, it'll wrap around to the list's end, again.
+         [[Slide to the previous item, in a given slideshow widget
 
-         @ingroup Slideshow */
+           The sliding animation $obj is set to use will be the
+           transition effect used, after this call is issued.
 
+           Note: If the beginning of the slideshow's internal list of items
+           is reached, it'll wrap around to the list's end, again.
+         ]]
       }
       item_nth_get @const {
-         /*@
-         Get the the item, in a given slideshow widget, placed at
-         position $nth, in its internal items list
-
-         @return The item stored in $obj at position $nth or $NULL,
-         if there's no item with that index (and on errors)
-
-         @ingroup Slideshow */
-         return: Elm.Widget_Item *;
+         [[Get the the item, in a given slideshow widget, placed at
+           position $nth, in its internal items list.
+         ]]
+         return: Elm.Widget_Item *; [[The item stored in $obj at position
+                                      $nth or $null if there's no item with
+                                      that index (and on errors).]]
          params {
-            @in nth: uint; /*@ The number of the item to grab a handle to (0 being
-            the first) */
+            @in nth: uint; [[The number of the item to grab a handle to
+                             (0 being the first).]]
          }
       }
       next {
-         /*@
-         Slide to the @b next item, in a given slideshow widget
-
-         The sliding animation $obj is set to use will be the
-         transition effect used, after this call is issued.
+         [[Slide to the next item, in a given slideshow widget.
 
-         @note If the end of the slideshow's internal list of items is
-         reached, it'll wrap around to the list's beginning, again.
-
-         @ingroup Slideshow */
+           The sliding animation $obj is set to use will be the
+           transition effect used, after this call is issued.
 
+           Note: If the end of the slideshow's internal list of items is
+           reached, it'll wrap around to the list's beginning, again.
+         ]]
       }
       clear {
-         /*@
-         Remove all items from a given slideshow widget
-
-         This removes (and deletes) all items in $obj, leaving it
-         empty.
-
-         @see elm_object_item_del(), to remove just one item.
-
-         @ingroup Slideshow */
+         [[Remove all items from a given slideshow widget.
 
+           This removes (and deletes) all items in $obj, leaving it empty.
+         ]]
       }
       item_add {
-         /*@
-         Add (append) a new item in a given slideshow widget.
-
-         @return A handle to the item added or $NULL, on errors
-
-         Add a new item to $obj's internal list of items, appending it.
-         The item's class must contain the function really fetching the
-         image object to show for this item, which could be an Evas image
-         object or an Elementary photo, for example. The $data
-         parameter is going to be passed to both class functions of the
-         item.
-
-         @see #Elm_Slideshow_Item_Class
-         @see elm_slideshow_item_sorted_insert()
-         @see elm_object_item_data_set()
-
-         @ingroup Slideshow */
-
-         return: Elm.Widget_Item *;
+         [[Add (append) a new item in a given slideshow widget.
+
+           Add a new item to $obj's internal list of items, appending it.
+           The item's class must contain the function really fetching the
+           image object to show for this item, which could be an Evas image
+           object or an Elementary photo, for example. The $data
+           parameter is going to be passed to both class functions of the
+           item.
+         ]]
+         return: Elm.Widget_Item *; [[A handle to the item added or $null on errors.]]
          params {
-            @in itc: const(Elm_Slideshow_Item_Class)*; /*@ The item class for the item */
-            @in data: const(void)*; /*@ The item's data */
+            @in itc: const(Elm_Slideshow_Item_Class)*; [[The item class for the item.]]
+            @in data: const(void)*; [[The item's data.]]
          }
       }
       item_sorted_insert {
-         /*@
-         Insert a new item into the given slideshow widget, using the $func
-         function to sort items (by item handles).
-
-         @return Returns The slideshow item handle, on success, or
-         $NULL, on errors
-
-         Add a new item to $obj's internal list of items, in a position
-         determined by the $func comparing function. The item's class
-         must contain the function really fetching the image object to
-         show for this item, which could be an Evas image object or an
-         Elementary photo, for example. The $data parameter is going to
-         be passed to both class functions of the item.
-
-         @see #Elm_Slideshow_Item_Class
-         @see elm_slideshow_item_add()
-
-         @ingroup Slideshow */
-
-         return: Elm.Widget_Item *;
+         [[Insert a new item into the given slideshow widget, using the
+           $func function to sort items (by item handles).
+
+           Add a new item to $obj's internal list of items, in a position
+           determined by the $func comparing function. The item's class
+           must contain the function really fetching the image object to
+           show for this item, which could be an Evas image object or an
+           Elementary photo, for example. The $data parameter is going to
+           be passed to both class functions of the item.
+         ]]
+         return: Elm.Widget_Item *; [[Returns The slideshow item handle,
+                                      on success, or $null on errors.]]
          params {
-            @in itc: const(Elm_Slideshow_Item_Class)*; /*@ The item class for the item */
-            @in data: const(void)*; /*@ The item's data */
-            @in func: Eina_Compare_Cb; /*@ The comparing function to be used to sort slideshow
-            items <b>by #Elm_Slideshow_Item_Class item handles</b> */
+            @in itc: const(Elm_Slideshow_Item_Class)*; [[The item class for the item.]]
+            @in data: const(void)*; [[The item's data.]]
+            @in func: Eina_Compare_Cb; [[The comparing function to be used to sort the slideshow
+                                         items by #Elm_Slideshow_Item_Class item handles.]]
          }
       }
    }