q66 pushed a commit to branch master.
http://git.enlightenment.org/core/efl.git/commit/?id=c93de19e227928288f2d64298ec8348373e0a8b5
commit c93de19e227928288f2d64298ec8348373e0a8b5
Author: Daniel Kolesa <d.kol...@osg.samsung.com>
Date: Thu Jun 18 11:01:12 2015 +0100
efl_model_base: convert docs
---
src/lib/efl/interfaces/efl_model_base.eo | 344 +++++++++++++++----------------
1 file changed, 162 insertions(+), 182 deletions(-)
diff --git a/src/lib/efl/interfaces/efl_model_base.eo
b/src/lib/efl/interfaces/efl_model_base.eo
index 40abf00..288ef3f 100644
--- a/src/lib/efl/interfaces/efl_model_base.eo
+++ b/src/lib/efl/interfaces/efl_model_base.eo
@@ -30,129 +30,85 @@ interface Efl.Model.Base ()
methods {
@property load_status {
get {
- /*@
- Get a load emodel current status.
+ [[Get a load emodel current status.
- @return: @c Efl_Model_Load_Status
+ By convention this means get the current model status.
+ Possible values are defined Efl_Model_Load_Status enumerator.
- By convention this means get the current model status.
- Possible values are defined Efl_Model_Load_Status enumerator.
+ See also @Efl_Model_Load_Status, @efl_model_load
- @see Efl_Model_Load_Status
- @see efl_model_load
-
- @since 1.14 */
- return: Efl.Model.Load_Status;
+ @since 1.14
+ ]]
+ return: Efl.Model.Load_Status;
}
}
@property properties {
get {
- /*@
- Get properties from model.
+ [[Get properties from model.
- @return: @c Efl_Model_Load_Status
+ properties_get is due to provide callers a way the fetch the
+ current properties implemented/used by the model. The event
+ EFL_MODEL_EVENT_PROPERTIES_CHANGE will be raised to notify
+ listeners of any modifications in the properties.
- properties_get is due to provide callers a way the fetch the
current
- properties implemented/used by the model.
- The event EFL_MODEL_EVENT_PROPERTIES_CHANGE will be raised to
notify listeners
- of any modifications in the properties.
+ See also @EFL_MODEL_EVENT_PROPERTIES_CHANGE.
- @see EFL_MODEL_EVENT_PROPERTIES_CHANGE
- @since 1.14 */
-
- return: Efl.Model.Load_Status;
+ @since 1.14
+ ]]
+ return: Efl.Model.Load_Status;
}
values {
- properties: const(array<const(char*)>*); /*@ array of current
properties */
+ properties: const(array<const(char*)>*); [[array of current
properties]]
}
}
@property property {
set {
- /*@
- Set a property value of a given property name.
-
- @return: @c EINA_TRUE, on success, @c EINA_FALSE in readonly
property or error
+ [[Set a property value of a given property name.
- The caller must ensure to call at least efl_model_prop_list
before being
- able to see/set properties.
- This function sets a new property value into given property
name. Once
- the operation is completed the concrete implementation should
raise
- EFL_MODEL_EVENT_PROPERTIES_CHANGE event in order to notify
listeners of the
- new value of the property.
+ The caller must ensure to call at least efl_model_prop_list
+ before being able to see/set properties. This function sets
+ a new property value into given property name. Once the
+ operation is completed the concrete implementation should
+ raise EFL_MODEL_EVENT_PROPERTIES_CHANGE event in order to
+ notify listeners of the new value of the property.
- If the model doesn't have the property then there are two
possibilities,
- either raise an error or create the new property in model
+ If the model doesn't have the property then there are two
+ possibilities, either raise an error or create the new
+ property in model
- @see efl_model_property_get
- @see EFL_MODEL_EVENT_PROPERTIES_CHANGE
- @since 1.14 */
+ See @efl_model_property_get,
@EFL_MODEL_EVENT_PROPERTIES_CHANGE
- return: Efl.Model.Load_Status;
+ @since 1.14
+ ]]
+ return: Efl.Model.Load_Status;
}
get {
- /*@
- Retrieve the value of a given property name.
-
- @return: @c Load Status, on success, @c
EFL_MODEL_LOAD_STATUS_ERROR otherwise
+ [[Retrieve the value of a given property name.
- property_get will only be available when load status is equal
to
- EFL_MODEL_LOAD_STATUS_LOADED.
+ property_get will only be available when load status is equal
+ to EFL_MODEL_LOAD_STATUS_LOADED.
- At this point the caller is free to get values from properties.
- The event EFL_MODEL_EVENT_PROPERTIES_CHANGE may be raised to
notify
- listeners of the property/value.
+ At this point the caller is free to get values from
properties.
+ The event EFL_MODEL_EVENT_PROPERTIES_CHANGE may be raised to
+ notify listeners of the property/value.
- @see efl_model_properties_get
- @see EFL_MODEL_EVENT_PROPERTIES_CHANGE
+ See @efl_model_properties_get,
@EFL_MODEL_EVENT_PROPERTIES_CHANGE
- @since 1.14 */
- return: Efl.Model.Load_Status;
+ @since 1.14
+ ]]
+ return: Efl.Model.Load_Status;
}
keys {
- property: const(char)*; /*@ Property name */
+ property: const(char)*; [[Property name]]
}
values {
- value: const(generic_value)*; /*@ New value */
+ value: const(generic_value)*; [[New value]]
}
}
@property children_slice {
get {
- /*@
- Get children slice OR full range.
-
- @return: @c Efl_Model_Load_Status. See below for more info.
-
- Before being able to get the children list the model status
must be
- on loaded status (EFL_MODEL_LOAD_STATUS_LOADED).
- However there may be circunstancies where the model could be
- in a different state, in such cases it is advisable
- to simply return: its current state, which will be
- of course, different than @c
EFL_MODEL_LOAD_STATUS_LOADED_CHILDREN.
- When children accessor is return:ed as NULL one should then
- test the current load status return:ed by @children_slice_get
- in order to check against an empty list or real error.
-
- children_slice_get behaves in two different ways, it may provide
- the slice if both @c start AND @c count are non-zero OR full
range otherwise.
-
- The return:ed Eina_Accessor must be freed when it is no longer
needed and
- eo_unref() must be invoked for children if caller wants a copy.
-
- Since 'slice' is a range, for example if we have 20 childs a
slice could be
- the range from 3(start) to 4(count), see:
- child 0 [no]
- child 1 [no]
- child 2 [yes]
- child 3 [yes]
- child 4 [yes]
- child 5 [yes]
- child 6 [no]
- child 7 [no]
-
- Optionally the user can call children_count_get to know
- the number of children so a valid range can be known in advance.
-
- Below are examples of both usage types: slices and full ranges.
+ /* doc FIXME: example
+ Below are examples of both usage types: slices and full
ranges.
@code
// Returns full list
@@ -162,18 +118,55 @@ interface Efl.Model.Base ()
eo_do(obj, efl_model_children_slice_get(5, 5,
&children_accessor));
@endcode
-
- @see efl_model_children_get
- @see efl_model_children_count_get
- @see efl_model_load
- @see efl_model_load_status_get
- @since 1.14 */
-
+ */
+ [[Get children slice OR full range.
+
+ Before being able to get the children list the model status
+ must be on loaded status (EFL_MODEL_LOAD_STATUS_LOADED).
+ However there may be circunstancies where the model could be
+ in a different state, in such cases it is advisable to simply
+ return: its current state, which will be of course, different
+ than EFL_MODEL_LOAD_STATUS_LOADED_CHILDREN.
+
+ When children accessor is returned as NULL one should then
+ test the current load status return:ed by @children_slice_get
+ in order to check against an empty list or real error.
+
+ children_slice_get behaves in two different ways, it may
+ provide the slice if both @c start AND @c count are non-zero
+ OR full range otherwise.
+
+ The return:ed Eina_Accessor must be freed when it is no longer
+ needed and eo_unref() must be invoked for children if caller
+ wants a copy.
+
+ Since 'slice' is a range, for example if we have 20 childs a
+ slice could be the range from 3(start) to 4(count), see:
+
+ child 0 [no]
+ child 1 [no]
+ child 2 [yes]
+ child 3 [yes]
+ child 4 [yes]
+ child 5 [yes]
+ child 6 [no]
+ child 7 [no]
+
+ Optionally the user can call children_count_get to know the
+ number of children so a valid range can be known in advance.
+
+ See @efl_model_children_get, @efl_model_children_count_get,
+ @efl_model_load, @efl_model_load_status_get
+
+ @since 1.14
+ ]]
return: Efl.Model.Load_Status;
}
keys {
- start: uint; /*@ Range begin - start from here. If start and
count are 0 slice is ignored.*/
- count: uint; /*@ Range size. If count and start are 0 slice is
ignored.*/
+ start: uint; [[Range begin - start from here. If start and
+ count are 0 slice is ignored.]]
+ count: uint; [[Range size. If count and start are 0 slice is
+ ignored.]]
}
values {
children_accessor: accessor<list<Eo.Base*>*>*;
@@ -181,22 +174,19 @@ interface Efl.Model.Base ()
}
@property children_count {
get {
- /*@
- Get children count.
+ [[Get children count.
- @return: @c EINA_TRUE, on success, @c EINA_FALSE otherwise
+ When efl_model_load is completed efl_model_coildren_count_get
+ can be use to get the number of children. children_count_get
+ can also be used before calling children_slice_get so a valid
+ range is known. Event EFL_MODEL_CHILDREN_COUNT_CHANGED is
+ emitted when count is finished.
- When efl_model_load is completed efl_model_coildren_count_get
can be use
- to get the number of children. children_count_get can also be
used
- before calling children_slice_get so a valid range is known.
- Event EFL_MODEL_CHILDREN_COUNT_CHANGED is emitted when count
is finished.
-
- @see efl_model_children_get
- @see efl_model_children_slice_get
- @see efl_model_load
- @see efl_model_load_status_get
- @since 1.14 */
+ See also @efl_model_children_get,
@efl_model_children_slice_get,
+ @efl_model_load, @efl_model_load_status_get.
+ @since 1.14
+ ]]
return: Efl.Model.Load_Status;
}
values {
@@ -204,108 +194,98 @@ interface Efl.Model.Base ()
}
}
load {
- /*@
- Load emodel.
-
- By convention this means loading data from an external source
and populating
- the models properties and children with it. For example in the
case of file
- system backed model, this means opening the relevant files and
reading the
- data from them(creating the properties and children from it).
- the model emit EFL_MODEL_EVENT_LOAD_STATUS after end with
Efl_Model_Load_Status
- @warning This convention should be followed, but no guarantees
of behaviour
+ [[Load emodel.
+
+ By convention this means loading data from an external source and
+ populating the models properties and children with it. For
example
+ in the case of file system backed model, this means opening the
+ relevant files and reading the data from them(creating the
+ properties and children from it). the model emit
+ EFL_MODEL_EVENT_LOAD_STATUS after end with Efl_Model_Load_Status
+
+ This convention should be followed, but no guarantees of
behaviour
by user defined types can be given.
- Alternatively is possible to use properties_load to load only
properties
- and children_load to load only children. If efl_model_load is
called then
- calling properties_load and/or children_load is not necessary.
+ Alternatively is possible to use properties_load to load only
+ properties and children_load to load only children. If
+ efl_model_load is called then calling properties_load
+ and/or children_load is not necessary.
- @see Efl_Model_Load_Status
- @see efl_model_properties_load
- @see efl_model_children_load
- @see efl_model_unload
- @see efl_model_load_status_get
+ See also @Efl_Model_Load_Status, @efl_model_properties_load,
+ @efl_model_children_load, @efl_model_unload,
+ @efl_model_load_status_get
- @since 1.14 */
+ @since 1.14
+ ]]
}
unload {
- /*@
- Unload emodel.
-
- By convention this means releasing data received/read from an
external source. For
- example of a database backed model this might mean releasing the
iterator for
- the currently loaded data or deleting a temporary table.
- the model emit EFL_MODEL_EVENT_LOAD_STATUS after end with model
load status
- @warning This convention should be followed, but no guarantees
of behaviour
+ [[Unload emodel.
+
+ By convention this means releasing data received/read from an
+ external source. For example of a database backed model this
+ might mean releasing the iterator for the currently loaded data
+ or deleting a temporary table. the model emit
+ EFL_MODEL_EVENT_LOAD_STATUS after end with model load status
+
+ This convention should be followed, but no guarantees of
behaviour
by user defined types can be given.
- @see Efl_Model_Load_Status
- @see efl_model_load
- @see efl_model_load_status_get
+ See also @Efl_Model_Load_Status, @efl_model_load,
+ @efl_model_load_status_get
- @since 1.14 */
+ @since 1.14
+ ]]
}
properties_load {
- /*@
- Properties emodel load.
-
- By convention this means loading data from an external source
and populating
- the models properties only. This method is a subset of
efl_model_load, meaning that
- it won't load children, it is a hint.
- For loadind both properties and children use efl_model_load
- instead.
+ [[Properties emodel load.
- @see efl_model_load
+ By convention this means loading data from an external source and
+ populating the models properties only. This method is a subset
+ of @efl_model_load, meaning that it won't load children, it is
+ a hint. For loadind both properties and children use
+ efl_model_load instead.
- @since 1.14 */
+ @since 1.14
+ ]]
}
children_load {
- /*@
- Children emodel load.
+ [[Children emodel load.
- By convention this means loading data from an external source
and populating
- the models children only. This method is a subset of
efl_model_load, meaning that
- it won't load properties. For loadind both properties and
children use efl_model_load
- instead.
+ By convention this means loading data from an external source and
+ populating the models children only. This method is a subset of
+ @efl_model_load, meaning that it won't load properties. For
+ loadind both properties and children use efl_model_load instead.
- @see efl_model_load
-
- @since 1.14 */
+ @since 1.14
+ ]]
}
child_add {
- /*@
- Add a new child.
-
- @return: @c Emodel* on success, @c NULL otherwise
+ [[Add a new child.
Add a new child, possibly dummy, depending on the implementation,
of a internal keeping. When the child is effectively
- added the event EFL_MODEL_EVENT_CHILD_ADD is then raised and the
new child
- is kept along with other children.
-
- @see EFL_MODEL_EVENT_CHILD_ADD
- @see load_status_get
+ added the event @EFL_MODEL_EVENT_CHILD_ADD is then raised and the
+ new child is kept along with other children.
- @since 1.14 */
+ See also @load_status_get.
+ @since 1.14
+ ]]
return: Eo.Base *;
}
child_del {
- /*@
- Remove a child.
-
- @return: @c Efl_Model_Load_Status on success, @c
EFL_MODEL_LOAD_STATUS_ERROR otherwise.
+ [[Remove a child.
Remove a child of a internal keeping. When the child is
effectively
- removed the event EFL_MODEL_EVENT_CHILD_REMOVED is then raised
to give a
- chance for listeners to perform any cleanup and/or update
references.
-
- @see EFL_MODEL_EVENT_CHILD_REMOVED
- @since 1.14 */
-
- return: Efl.Model.Load_Status;
+ removed the event @EFL_MODEL_EVENT_CHILD_REMOVED is then raised
to
+ give a chance for listeners to perform any cleanup and/or update
+ references.
+ @since 1.14
+ ]]
+ return: Efl.Model.Load_Status;
params {
- @in child: Eo.Base*; /*@ Child to be removed */
+ @in child: Eo.Base*; [[Child to be removed]]
}
}
}
--
