On 11/06/2013 03:31 AM, Cedric BAIL wrote:
> On Tue, Nov 5, 2013 at 6:51 PM, Yakov Goldberg <yako...@samsung.com> wrote:
>> On 11/05/2013 08:20 AM, Cedric BAIL wrote:
>>> On Tue, Nov 5, 2013 at 12:42 AM, Yakov Goldberg <yako...@samsung.com> wrote:
>>>> Here is autogenerated (a little prettyfied and shortened) example of eo
>>>> file.
>>>> http://pastebin.com/ERQphzNk
>>>> I'm using my own python code from eo_bindings, where I was parsing c/h
>>>> files to get all eo information.
>>>>
>>>> Some explanations:
>>>> "name" - class name from Eo class description. We check that it is unique.
>>>> "inherits" - names of parent classes
>>>> "constructors" - (actually it is a method, just put it into separate
>>>> section). Here you will meet only custom cunstructors.
>>>> here "win_constructor" is a name
>>>> "comment" - comment
>>>> parameters: 2d array
>>>> ["in","const","char*","name",""],
>>>> direction, modifier, type, name, comment
>>>> maybe modifier is not needed, (but I already parsed it)
>>> I must say that I don't like the parameters syntax at all. I think
>>> something along the following line would have been better :
>>> in : [ { "name" : "const char *" } ]. Also I am starting thinking that
>>> we should have comment in doxygen form inside the JSON itself that
>>> could then be put along the generated code.
>>> For example "item_insert_before" would become :
>>>
>>> "item_insert_before": {
>>> /* This inserts an item before another in the list. It will be in the
>>> * same tree level or group as the item it is inserted before.
>>> *
>>> * @see elm_genlist_item_append()
>>> * @see elm_genlist_item_prepend()
>>> * @see elm_genlist_item_insert_after()
>>> * @see elm_object_item_del()
>>> *
>>> * @ingroup Genlist
>>> */
>>> "brief": "Insert an item before another in a genlist widget",
>>> "parameters": [
>>> in : [
>>> { "itc" : "const Elm_Genlist_Item_Class*" }, /* @param
>>> itc The item class for the item */
>>> { "data" : "const void*" }, /* @param data The item data */
>>> { "parent" : "Elm_Object_Item*" }, /* @param parent The
>>> parent item, or NULL if none */
>>> { "before_it" : "Elm_Object_Item*" }, /* @param before
>>> The item to place this new one before. */
>>> { "type" : "Elm_Genlist_Item_Type" }, /* @param type Item
>>> type */
>>> { "func" : "Evas_Smart_Cb" }, /* @param func
>>> Convenience function called when the item is selected */
>>> { "func_data" : "const void *" } /* @param func_data
>>> Data passed to @p func above. */
>>> ],
>>> out : [
>>> { "ret" : "Elm_Object_Item*" } /* @return A handle to
>>> the item added or @c NULL if not possible */
>>> ]
>>> ]
>>> ]
>>> },
>> What's if I want to put in/out/inout parameters all mixed, wouldn't it
>> be nicier to put them like this.
>> Also comments outside will ruin JSON structure. So I will try to keep
>> giving proper json examples a while.
>> "parameters" : [
>> {"par1" : ["in", "int", "Comment1"]},
>> {"par2" : ["out", "Eina_Bool*", "Comment2"]},
>> {"par3" : ["inout", "char **", "Comment3"]},
>> {"par4" : ["in", "Typedefed_Enum", "Comment4"]},
>> ]
> I must say that I am against mixing in and out. I may be wrong, but I
> think that our current API does follow this pattern of in, out ?
I think, yes. They follow this pattern, but what's for future classes
and API?
Maybe we simply should start with explanations. Which way is prefered?
- making everything as generic as possible.
or
- limit syntax with conventions, so we can say "in EFL "in" - params in
the beginning, "out" - in the end"
>
>> Also some nicier implements
>> "implements": [
>> {"elm_interface_scrollable": [ "policy", "set_get" ]},
>> {"Evas_Pbject_Smart": [ "move", "method" ]},
>> ]
> I must say that I don't understand the previous two lines :-) Why do
> we need to say if it is a method ? It should be able to find it easily
> with only the name, no ?
In most cases - yes. And probably the only example I can give is:
elm_widget_theme/_set/_get .
So in eo file for Elm Widget we will have:
"methods": {
"theme": {
"comment": "'Virtual' function on the widget being re-themed.",
"parameters": [
["out", "", "Eina_Bool", "ret", "" ]
]
}
}
"properties" :
{
"theme": {
"comment_set": "No description supplied by the EAPI.",
"comment_get": "No description supplied by the EAPI.",
"parameters": [
[ "", "Elm_Theme*", "th", "" ]
]
}
}
So when overriding "theme" i need to tell which one of them I want to
override.
"implements": [
{"elm_widget": [ "theme", "method" ]},
{"elm_widget": [ "theme", "set" ]}
]
Example: 2.
Also we can put "implemets" section into "method" and "property" sections.
But for properties still need to be marked, which of them should be overriden.
Example
"methods" : {
"some_additional_section_to_separate_methods_from_implements" :
{
/* methods description */
},
"implements": [
{"elm_widget": "theme"}
]
}
"properties" : {
"some_additional_section_to_separate_properties_from_implements" :
{
/* properties description */
},
"implements": [
{"elm_widget": ["theme", "set"]}
]
}
The question is: how is it more comfort?. To list overriden methods and
properties together at the end.
Or separately in "methods" and "properties" sections.
>> About in-built doxygen:
>> All API will be autogenerated with proper prefix, so hardcoded "@see
>> elm_genlist_item_append()" doesn't make sence.
>> Also we will need to add description of parameters into this
>> doxy-description, so it will be easier to generate it from the scratch.
>> Yes, we want have references to other funcs, need to think how to add it.
> Hum, that is right. We need to think about having proper documentation
> from the beginning. So maybe just a stripped version of doxygen that
> will be extended when generating code ?
>
>>>> Properties.
>>>> Property can be set/get; only set, only get; this is saved in "type"
>>>> field: "rw"(or no tag), "ro", "wo".
>>>> How do I determine the type? If all parameters are "in" for some
>>>> func which ends with "_set"
>>>> and are "out" for some func which ends with "_get" this will be
>>>> set/get property. If this condition fails, they will be methods.
>>> Same for property we should be fine with something like :
>>> "keyboard_win": {
>>> "brief": "whether the window is a keyboard.",
>>> "access": "rw",
>>> "parameters": [
>>> [ { "is_keyboard" : "Eina_Bool" } ]
>>> ]
>> Cedric, could you please comment situation around "const" modifier.
>> for example:
>>
>> "parents_list": {
>> "brief": "List of some parents",
>> "access": "rw",
>> "parameters": [
>> [ { "parents_list" : "Eina_List*" } ]
>> ]
>> So here can be lot situations:
>> parents_list_set can only assign pointer or copy a list(of course in this
>> case function must be named ..._list_copy, but world is not perfect)
>> parents_list_get can return mutable or inmutable list...
>> So, how to understand whenever "const" is needed?
> Eina_List is a tricky one, you can't modify it if you don't return it
> at the end or it may be broken for the caller. If you return an const
> Eina_List or give a const Eina_List it is expected that the caller
> will just make a copy of it. If it is not const, it will take
> ownership of it and the caller can't use it anymore. That has been our
> convention in EFL as far as I know. So in this case parents_list
> should be of type const Eina_List* if it does a copy.
>
>> How to understand if const is needed for only set or get property, or for
>> both.
>>
> Hum can't we extract that knowledge from current code ?
As I understand, if "in" parameter is const, so "out" parameter will be
const too. So It can be taken from current code.
Looks like the only place where it is not like that is:
EAPI void evas_object_textblock_style_set(Evas_Object *obj,
Evas_Textblock_Style *ts) EINA_ARG_NONNULL(1);
EAPI const Evas_Textblock_Style *evas_object_textblock_style_get(const
Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
But maybe it is mistake?
If not, we need to have property with different parameter types for
"set" and "get" parts of property.
------------------------------------------------------------------------------
November Webinars for C, C++, Fortran Developers
Accelerate application performance with scalable programming models. Explore
techniques for threading, error checking, porting, and tuning. Get the most
from the latest Intel processors and coprocessors. See abstracts and register
http://pubads.g.doubleclick.net/gampad/clk?id=60136231&iu=/4140/ostg.clktrk
_______________________________________________
enlightenment-devel mailing list
enlightenment-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/enlightenment-devel
