From 38a1d15016ee3dfcac01d057fc9d361cda11f528 Mon Sep 17 00:00:00 2001 From: Kai Huuhko Date: Sat, 7 Jun 2014 18:17:40 +0300 Subject: [PATCH] Eolian: Documentation, fix show() --- doc/eolian/eolian.rst | 4 + doc/index.rst | 5 + efl/eolian/__init__.pyx | 237 +++++++++++++++++++--------------------- setup.py | 2 +- 4 files changed, 125 insertions(+), 123 deletions(-) create mode 100644 doc/eolian/eolian.rst diff --git a/doc/eolian/eolian.rst b/doc/eolian/eolian.rst new file mode 100644 index 0000000..ce3af0c --- /dev/null +++ b/doc/eolian/eolian.rst @@ -0,0 +1,4 @@ +:mod:`eolian` Module +-------------------- + +.. automodule:: efl.eolian.__init__ diff --git a/doc/index.rst b/doc/index.rst index ac42901..7dd40d2 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -41,6 +41,11 @@ EO .. toctree:: eo/eo.rst +Eolian +------ + +.. toctree:: eolian/eolian + Ecore ----- diff --git a/efl/eolian/__init__.pyx b/efl/eolian/__init__.pyx index 1f94bc6..72134fe 100644 --- a/efl/eolian/__init__.pyx +++ b/efl/eolian/__init__.pyx @@ -124,8 +124,8 @@ def directory_scan(directory): The found files are just open to extract the class name. - @param[in] dir the directory to scan - @return EINA_TRUE on success, EINA_FALSE otherwise. + :param dir: the directory to scan + :return: True on success, False otherwise. """ if isinstance(directory, unicode): directory = PyUnicode_AsUTF8String(directory) @@ -135,29 +135,31 @@ def all_eo_files_parse(): """Force parsing of all the files located in the directories given in eolian_directory_scan.. - @return EINA_TRUE on success, EINA_FALSE otherwise. + :return: True on success, False otherwise. - @see eolian_directory_scan + :see: :py:func:`directory_scan` """ return bool(eolian_all_eo_files_parse()) -def show(Class klass): +def show(Class klass=None): """Show information about a given class. - If klass is NULL, this function will print information of + If klass is None, this function will print information of all the classes stored into the database. - @param[in] klass the class to show + :param klass: the class to show """ - return bool(eolian_show(klass.klass)) + return bool(eolian_show( + klass.klass if klass is not None else NULL + )) def class_find_by_name(class_name): """Finds a class by its name - @param[in] class_name name of the class to find. - @return the class + :param class_name: name of the class to find. + :return: the class """ if isinstance(class_name, unicode): class_name = PyUnicode_AsUTF8String(class_name) @@ -168,8 +170,8 @@ def class_find_by_name(class_name): def class_find_by_file(file_name): """Finds a class by its location (.eo file) - @param[in] file_name filename where the class is stored. - @return the class stored in the file + :param file_name: filename where the class is stored. + :return: the class stored in the file """ if isinstance(file_name, unicode): file_name = PyUnicode_AsUTF8String(file_name) @@ -185,6 +187,9 @@ cdef class Class(object): cdef _set_obj(self, uintptr_t obj): self.klass = obj + def __init__(self): + pass + property filename: """Returns the name of the file containing the given class. @@ -218,18 +223,18 @@ cdef class Class(object): property namespaces_list: """Returns the namespaces list of the given class. - @param[in] class the class. - @return the namespaces list of the class on success or NULL otherwise. + :type: list of strings """ def __get__(self): - return eina_list_strings_to_python_list(eolian_class_namespaces_list_get(self.klass)) + return eina_list_strings_to_python_list( + eolian_class_namespaces_list_get(self.klass) + ) property type: """Returns the class type of the given class - @param[in] klass the class - @return the class type + :type: :ref:`Eolian_Class_Type` """ def __get__(self): @@ -274,19 +279,19 @@ cdef class Class(object): property inherits_list: """Returns the names list of the inherit classes of a class - @param[in] klass the class - @return the list + :type: list of strings """ def __get__(self): - return eina_list_strings_to_python_list(eolian_class_inherits_list_get(self.klass)) + return eina_list_strings_to_python_list( + eolian_class_inherits_list_get(self.klass) + ) def functions_list_get(self, Eolian_Function_Type func_type): """Returns a list of functions of a class. - @param[in] klass the class - @param[in] func_type type of the functions to insert into the list. - @return the list of Eolian_Function + :param func_type: type of the functions to insert into the list. + :return: the list of Eolian_Function """ return eina_list_obj_to_python_list( @@ -299,8 +304,7 @@ cdef class Class(object): property implements: """Get the list of overriding functions defined in a class. - @param[in] klass the class. - @return a list of Eolian_Implement handles + :type: list of :py:class:`Implement` """ def __get__(self): @@ -311,8 +315,7 @@ cdef class Class(object): property events: """Get the list of events defined in a class. - @param[in] klass the class. - @return a list of Eolian_Event handles + :type: list of :py:class:`Event` """ def __get__(self): @@ -324,8 +327,7 @@ cdef class Class(object): """Indicates if the class constructor has to invoke a non-generated class constructor function. - @param[in] klass the class. - @return EINA_TRUE if the invocation is needed, EINA_FALSE otherwise. + :type: bool """ def __get__(self): @@ -335,8 +337,7 @@ cdef class Class(object): """Indicates if the class destructor has to invoke a non-generated class destructor function. - @param[in] klass the class. - @return EINA_TRUE if the invocation is needed, EINA_FALSE otherwise. + :type: bool """ def __get__(self): @@ -345,13 +346,13 @@ cdef class Class(object): def function_find_by_name(self, func_name, Eolian_Function_Type f_type): """Find a function in a class by its name and type - @param[in] klass the class - @param[in] func_name name of the function - @param[in] f_type type of the function - @return the function id if found, NULL otherwise. + :param func_name: name of the function + :param f_type: type of the function + :return: the function id if found, None otherwise. """ - if isinstance(func_name, unicode): func_name = PyUnicode_AsUTF8String(func_name) + if isinstance(func_name, unicode): + func_name = PyUnicode_AsUTF8String(func_name) return eolian_obj_to_python_obj( eolian_class_function_find_by_name( self.klass, func_name, f_type @@ -363,7 +364,7 @@ cdef class Class(object): def class_names_list_get(): """Returns the names list of all the classes stored into the database. - @return the list + :return: the list Returns the list of class names of the database @@ -379,11 +380,13 @@ cdef class Function(object): cdef _set_obj(self, uintptr_t obj): self.function_id = obj + def __init__(self): + pass + property type: """Returns the type of a function - @param[in] function_id Id of the function - @return the function type + :type: :ref:`Eolian_Function_Type` """ def __get__(self): @@ -392,8 +395,7 @@ cdef class Function(object): property scope: """Returns the scope of a function - @param[in] function_id Id of the function - @return the function scope + :type: :ref:`Eolian_Function_Scope` """ def __get__(self): @@ -402,8 +404,7 @@ cdef class Function(object): property name: """Returns the name of a function - @param[in] function_id Id of the function - @return the function name + :type: string """ def __get__(self): @@ -412,9 +413,8 @@ cdef class Function(object): def data_get(self, key): """Returns a specific data for a function. - @param[in] function_id Id of the function - @param[in] key key to access the data - @return the data. + :param key: key to access the data + :return: the data. """ if isinstance(key, unicode): key = PyUnicode_AsUTF8String(key) @@ -423,8 +423,7 @@ cdef class Function(object): def is_virtual_pure_get(self, Eolian_Function_Type f_type): """Indicates if a function is virtual pure. - @param[in] function_id Id of the function - @return EINA_TRUE if virtual pure, EINA_FALSE othrewise.. + :return: True if virtual pure, False otherwise.. """ return bool(eolian_function_is_virtual_pure(self.function_id, f_type)) @@ -432,9 +431,8 @@ cdef class Function(object): def description_get(self, key): """Returns a specific description for a function. - @param[in] function_id Id of the function - @param[in] key key to access the description - @return the description. + :param key: key to access the description + :return: the description. """ if isinstance(key, unicode): key = PyUnicode_AsUTF8String(key) @@ -443,12 +441,12 @@ cdef class Function(object): def parameter_get(self, param_name): """Returns a parameter of a function pointed by its id. - @param[in] function_id Id of the function - @param[in] param_name Name of the parameter - @return a handle to this parameter. + :param param_name: Name of the parameter + :return: a handle to this parameter. """ - if isinstance(param_name, unicode): param_name = PyUnicode_AsUTF8String(param_name) + if isinstance(param_name, unicode): + param_name = PyUnicode_AsUTF8String(param_name) return eolian_obj_to_python_obj( eolian_function_parameter_get( self.function_id, param_name @@ -459,8 +457,7 @@ cdef class Function(object): property property_keys_list: """Returns a list of keys params of a given function. - @param[in] function_id Id of the function - @return list of Eolian_Function_Parameter + :type: list of :py:class:`FunctionParameter` """ def __get__(self): @@ -471,20 +468,19 @@ cdef class Function(object): property property_values_list: """Returns a list of values params of a given function. - @param[in] function_id Id of the function - @return list of Eolian_Function_Parameter + :type: list of :py:class:`FunctionParameter` """ def __get__(self): return eina_list_obj_to_python_list( - eolian_property_values_list_get(self.function_id), FunctionParameter + eolian_property_values_list_get(self.function_id), + FunctionParameter ) property parameters_list: """Returns a list of parameter handles for a method/ctor/dtor. - @param[in] function_id Id of the function - @return list of Eolian_Function_Parameter + :type: list of :py:class:`FunctionParameter` """ def __get__(self): @@ -495,12 +491,11 @@ cdef class Function(object): def return_type_get(self, Eolian_Function_Type ftype): """Get the return type of a function. - @param[in] function_id id of the function - @param[in] ftype type of the function - @return the return type of the function + :param ftype: type of the function + :return: the return type of the function - The type of the function is needed because a given function can represent a - property, that can be set and get functions. + The type of the function is needed because a given function can + represent a property, that can be set and get functions. """ return _ctouni(eolian_function_return_type_get( @@ -510,9 +505,8 @@ cdef class Function(object): def return_types_list_get(self, Eolian_Function_Type ftype): """Get a list of all the types of a function return - @param[in] foo_id Function Id - @param[in] ftype Function Type - @return the types of the function return + :param ftype: Function Type + :return: the types of the function return """ return eolian_obj_to_python_obj( @@ -525,13 +519,12 @@ cdef class Function(object): def return_dflt_value_get(self, Eolian_Function_Type ftype): """Get the return default value of a function. - @param[in] function_id id of the function - @param[in] ftype type of the function - @return the return default value of the function + :param ftype: type of the function + :return: the return default value of the function The return default value is needed to return an appropriate value if an error occurs (eo_do failure...). - The default value is not mandatory, so NULL can be returned. + The default value is not mandatory, so None can be returned. """ return _ctouni(eolian_function_return_dflt_value_get( @@ -541,12 +534,11 @@ cdef class Function(object): def return_comment_get(self, Eolian_Function_Type ftype): """Get the return comment of a function. - @param[in] function_id id of the function - @param[in] ftype type of the function - @return the return comment of the function + :param ftype: type of the function + :return: the return comment of the function - The type of the function is needed because a given function can represent a - property, that can be set and get functions. + The type of the function is needed because a given function can + represent a property, that can be set and get functions. """ return _ctouni(eolian_function_return_comment_get( @@ -556,12 +548,11 @@ cdef class Function(object): def return_is_warn_unused_get(self, Eolian_Function_Type ftype): """Indicates if a function return is warn-unused. - @param[in] function_id id of the function - @param[in] ftype type of the function - @return EINA_TRUE is warn-unused, EINA_FALSE otherwise. + :param ftype: type of the function + :return: True is warn-unused, False otherwise. - The type of the function is needed because a given function can represent a - property, that can be set and get functions. + The type of the function is needed because a given function can + represent a property, that can be set and get functions. """ return bool(eolian_function_return_is_warn_unused( @@ -571,8 +562,7 @@ cdef class Function(object): property object_is_const: """Indicates if a function object is const. - @param[in] function_id id of the function - @return EINA_TRUE if the object is const, EINA_FALSE otherwise + :return: True if the object is const, False otherwise """ def __get__(self): @@ -586,14 +576,14 @@ cdef class FunctionParameter(object): cdef _set_obj(self, uintptr_t obj): self.param = obj + def __init__(self): + pass + property information: """Get information about a function parameter - @param[in] param_desc parameter handle - @param[out] param_dir in/out/inout - @param[out] type type of the parameter - @param[out] name name of the parameter - @param[out] description description of the parameter + :type: :ref:`Eolian_Parameter_Dir` direction, string type, string name, + string description """ def __get__(self): @@ -605,13 +595,14 @@ cdef class FunctionParameter(object): eolian_parameter_information_get( self.param, ¶m_dir, &type, &name, &description ) - return (param_dir, _ctouni(type), _ctouni(name), _ctouni(description)) + return ( + param_dir, _ctouni(type), _ctouni(name), _ctouni(description) + ) property type: """Get type of a parameter - @param[in] param_desc parameter handle - @return the type of the parameter + :type: string """ def __get__(self): @@ -620,8 +611,7 @@ cdef class FunctionParameter(object): property types_list: """Get a list of all the types of a parameter - @param[in] param_desc parameter handle - @return the types of the parameter + :type: :py:class:`Type` """ def __get__(self): @@ -632,8 +622,7 @@ cdef class FunctionParameter(object): property name: """Get name of a parameter - @param[in] param_desc parameter handle - @return the name of the parameter + :type: string """ def __get__(self): @@ -645,9 +634,9 @@ cdef class FunctionParameter(object): This function is relevant for properties, to know if a parameter is a const parameter in the get operation. - @param[in] param_desc parameter handle - @param[in] is_get indicates if the information needed is for get or set. - @return EINA_TRUE if const in get, EINA_FALSE otherwise + :param bool is_get: indicates if the information needed is for get or + set. + :return: True if const in get, False otherwise """ return bool(eolian_parameter_const_attribute_get(self.param, is_get)) @@ -655,8 +644,7 @@ cdef class FunctionParameter(object): property is_nonull: """Indicates if a parameter cannot be NULL. - @param[in] param_desc parameter handle - @return EINA_TRUE if cannot be NULL, EINA_FALSE otherwise + :type: bool """ def __get__(self): @@ -670,6 +658,9 @@ cdef class Type(object): cdef _set_obj(self, uintptr_t obj): self.etype = obj + def __init__(self): + pass + def __next__(self): cdef: const char *type @@ -689,13 +680,13 @@ cdef class Type(object): """Get information on given type. An Eolian type is an inlist of basic C types. For example: - Eina_List * contains two basic types. - The first Eolian type of the list stores Eina_List *, the next one Eo *. + ``Eina_List * `` contains two basic types. + The first Eolian type of the list stores ``Eina_List *``, the next one + ``Eo *``. - @param[in] etype Eolian type - @param[out] type C type - @param[out] own indicates if the ownership has to pass to the caller/callee. - @return the next type of the list. + :return: C type, ownership + (indicates if the ownership has to pass to the caller/callee.) + :rtype: (string, bool) """ def __get__(self): @@ -720,11 +711,13 @@ cdef class Implement(object): cdef _set_obj(self, uintptr_t obj): self.impl = obj + def __init__(self): + pass + property full_name: """Get full string of an overriding function (implement). - @param[in] impl handle of the implement - @return the full string. + :type: string """ def __get__(self): @@ -733,11 +726,9 @@ cdef class Implement(object): property information: """Get information about an overriding function (implement). - @param[in] impl handle of the implement - @param[out] class overridden class - @param[out] func overridden function - @param[out] type type of the overridden function - @return EINA_TRUE on success, EINA_FALSE otherwise. + :type: overridden :py:class:`Class`, overridden :py:func:`Function`, + overridden :ref:`Eolian_Function_Type` + :raise RuntimeError: on failure """ def __get__(self): @@ -766,13 +757,15 @@ cdef class Event(object): cdef _set_obj(self, uintptr_t obj): self.event = obj + def __init__(self): + pass + property information: """Get information about an event. - @param[in] event handle of the event - @param[out] event_name name of the event - @param[out] event_desc description of the event - @return EINA_TRUE on success, EINA_FALSE otherwise. + :type: name of the event (string), type of the event (string), + description of the event (string) + :raise RuntimeError: on failure """ def __get__(self): @@ -792,8 +785,8 @@ cdef class Event(object): def type_find_by_alias(alias): """Find the type for a certain alias - @param[in] alias alias of the type definition - @return real type of the type definition + :param alias: alias of the type definition + :return: real type of the type definition """ if isinstance(alias, unicode): alias = PyUnicode_AsUTF8String(alias) diff --git a/setup.py b/setup.py index 713a3e0..822cb7b 100755 --- a/setup.py +++ b/setup.py @@ -192,7 +192,7 @@ if set(("build", "build_ext", "install", "bdist", "sdist")) & set(sys.argv): # === Eolian === eol_cflags, eol_libs = pkg_config('Eolian', 'eolian', EFL_MIN_VERSION) eol_ext = Extension( - "eolian", ["efl/eolian/__init__" + module_suffix], + "eolian.__init__", ["efl/eolian/__init__" + module_suffix], define_macros=[('EFL_BETA_API_SUPPORT', None)], #include_dirs=['include/'], extra_compile_args=eol_cflags + eina_cflags,