q66 pushed a commit to branch master.
http://git.enlightenment.org/core/efl.git/commit/?id=ba033a4cfc6d6e072ac39e881459a48fa27913d1
commit ba033a4cfc6d6e072ac39e881459a48fa27913d1
Author: Daniel Kolesa <d.kol...@osg.samsung.com>
Date: Wed Jun 3 16:16:53 2015 +0100
eolian: add documentation handling API
This adds new APIs that deal with the new documentation syntax
provided by Eolian. The old doc comment APIs are considered
deprecated from now on and will be removed.
@feature
---
src/lib/eolian/Eolian.h | 121 +++++++++++++++++++
src/lib/eolian/database_class_api.c | 7 ++
src/lib/eolian/database_event_api.c | 7 ++
src/lib/eolian/database_function_api.c | 23 ++++
src/lib/eolian/database_function_parameter_api.c | 7 ++
src/lib/eolian/database_type_api.c | 25 ++++
src/lib/eolian/database_var_api.c | 7 ++
src/lib/eolian/eolian_database.c | 14 +++
src/tests/eolian/data/docs.eo | 2 +
src/tests/eolian/eolian_parsing.c | 144 ++++++++++++++++++++++-
10 files changed, 356 insertions(+), 1 deletion(-)
diff --git a/src/lib/eolian/Eolian.h b/src/lib/eolian/Eolian.h
index 8f74460..c749beb 100644
--- a/src/lib/eolian/Eolian.h
+++ b/src/lib/eolian/Eolian.h
@@ -701,6 +701,16 @@ EAPI Eina_Iterator *eolian_all_classes_get(void);
EAPI Eina_Stringshare *eolian_class_description_get(const Eolian_Class *klass);
/*
+ * @brief Returns the documentation of a class.
+ *
+ * @param[in] klass the class
+ * @return the documentation of a class
+ *
+ * @ingroup Eolian
+ */
+EAPI const Eolian_Documentation *eolian_class_documentation_get(const
Eolian_Class *klass);
+
+/*
* @brief Returns the legacy prefix of a class
*
* @param[in] klass the class
@@ -831,6 +841,17 @@ EAPI Eina_Stringshare *eolian_function_legacy_get(const
Eolian_Function *functio
EAPI Eina_Stringshare *eolian_function_description_get(const Eolian_Function
*function_id, Eolian_Function_Type f_type);
/*
+ * @brief Returns a documentation for a function.
+ *
+ * @param[in] function_id Id of the function
+ * @param[in] f_type The function type, for property get/set distinction.
+ * @return the documentation or NULL.
+ *
+ * @ingroup Eolian
+ */
+EAPI const Eolian_Documentation *eolian_function_documentation_get(const
Eolian_Function *function_id, Eolian_Function_Type f_type);
+
+/*
* @brief Indicates if a function is virtual pure.
*
* @param[in] function_id Id of the function
@@ -1009,6 +1030,16 @@ EAPI Eina_Stringshare *eolian_parameter_name_get(const
Eolian_Function_Parameter
EAPI Eina_Stringshare *eolian_parameter_description_get(const
Eolian_Function_Parameter *param);
/*
+ * @brief Get documentation of a parameter
+ *
+ * @param[in] param_desc parameter handle
+ * @return the documentation of the parameter or NULL
+ *
+ * @ingroup Eolian
+ */
+EAPI const Eolian_Documentation *eolian_parameter_documentation_get(const
Eolian_Function_Parameter *param);
+
+/*
* @brief Indicates if a parameter cannot be NULL.
*
* @param[in] param_desc parameter handle
@@ -1083,6 +1114,20 @@ eolian_function_return_default_value_get(const
Eolian_Function *foo_id, Eolian_F
EAPI Eina_Stringshare *eolian_function_return_comment_get(const
Eolian_Function *foo_id, Eolian_Function_Type ftype);
/*
+ * @brief Get the return docs of a function.
+ *
+ * @param[in] function_id id of the function
+ * @param[in] ftype type of the function
+ * @return the return docs 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.
+ *
+ * @ingroup Eolian
+ */
+EAPI const Eolian_Documentation
*eolian_function_return_documentation_get(const Eolian_Function *foo_id,
Eolian_Function_Type ftype);
+
+/*
* @brief Indicates if a function return is warn-unused.
*
* @param[in] function_id id of the function
@@ -1316,6 +1361,16 @@ EAPI const Eolian_Type *eolian_event_type_get(const
Eolian_Event *event);
EAPI Eina_Stringshare *eolian_event_description_get(const Eolian_Event *event);
/*
+ * @brief Get the documentation of an event.
+ *
+ * @param[in] event the event handle
+ * @return the documentation or NULL
+ *
+ * @ingroup Eolian
+ */
+EAPI const Eolian_Documentation *eolian_event_documentation_get(const
Eolian_Event *event);
+
+/*
* @brief Returns the scope of an event
*
* @param[in] event the event handle
@@ -1521,6 +1576,16 @@ EAPI Eina_Stringshare
*eolian_type_struct_field_name_get(const Eolian_Struct_Typ
EAPI Eina_Stringshare *eolian_type_struct_field_description_get(const
Eolian_Struct_Type_Field *fl);
/*
+ * @brief Get the documentation of a field of a struct type.
+ *
+ * @param[in] fl the field.
+ * @return the documentation.
+ *
+ * @ingroup Eolian
+ */
+EAPI const Eolian_Documentation
*eolian_type_struct_field_documentation_get(const Eolian_Struct_Type_Field *fl);
+
+/*
* @brief Get the type of a field of a struct type.
*
* @param[in] fl the field.
@@ -1588,6 +1653,16 @@ EAPI Eina_Stringshare
*eolian_type_enum_field_c_name_get(const Eolian_Enum_Type_
EAPI Eina_Stringshare *eolian_type_enum_field_description_get(const
Eolian_Enum_Type_Field *fl);
/*
+ * @brief Get the documentation of a field of an enum type.
+ *
+ * @param[in] fl the field.
+ * @return the documentation.
+ *
+ * @ingroup Eolian
+ */
+EAPI const Eolian_Documentation
*eolian_type_enum_field_documentation_get(const Eolian_Enum_Type_Field *fl);
+
+/*
* @brief Get the value of a field of an enum type.
*
* When the @c force parameter is EINA_FALSE, this will only return values for
@@ -1625,6 +1700,17 @@ EAPI Eina_Stringshare
*eolian_type_enum_legacy_prefix_get(const Eolian_Type *tp)
EAPI Eina_Stringshare *eolian_type_description_get(const Eolian_Type *tp);
/*
+ * @brief Get the documentation of a struct/alias type.
+ *
+ * @param[in] tp the type.
+ * @return the documentation when @c tp is EOLIAN_TYPE_STRUCT or
+ * EOLIAN_TYPE_STRUCT_OPAQUE, NULL otherwise.
+ *
+ * @ingroup Eolian
+ */
+EAPI const Eolian_Documentation *eolian_type_documentation_get(const
Eolian_Type *tp);
+
+/*
* @brief Get the filename of a struct/alias type.
*
* @param[in] tp the type.
@@ -1993,6 +2079,16 @@ EAPI Eolian_Variable_Type eolian_variable_type_get(const
Eolian_Variable *var);
EAPI Eina_Stringshare *eolian_variable_description_get(const Eolian_Variable
*var);
/*
+ * @brief Get the documentation of a variable.
+ *
+ * @param[in] var the variable.
+ * @return the documentation or NULL.
+ *
+ * @ingroup Eolian
+ */
+EAPI const Eolian_Documentation *eolian_variable_documentation_get(const
Eolian_Variable *var);
+
+/*
* @brief Get the filename of a variable.
*
* @param[in] var the variable.
@@ -2129,6 +2225,31 @@ EAPI const Eolian_Type
*eolian_declaration_data_type_get(const Eolian_Declaratio
*/
EAPI const Eolian_Variable *eolian_declaration_variable_get(const
Eolian_Declaration *decl);
+/*
+ * @brief Get the summary of the documentation.
+ *
+ * This should never return NULL unless the input is invalid.
+ *
+ * @param[in] doc the documentation
+ * @return the summary or NULL
+ *
+ * @ingroup Eolian
+ */
+EAPI Eina_Stringshare *eolian_documentation_summary_get(const
Eolian_Documentation *doc);
+
+/*
+ * @brief Get the description of the documentation.
+ *
+ * This can return NULL if the description wasn't specified or
+ * if the input is wrong.
+ *
+ * @param[in] doc the documentation
+ * @return the description or NULL
+ *
+ * @ingroup Eolian
+ */
+EAPI Eina_Stringshare *eolian_documentation_description_get(const
Eolian_Documentation *doc);
+
#endif
/**
diff --git a/src/lib/eolian/database_class_api.c
b/src/lib/eolian/database_class_api.c
index e4c9723..ae74977 100644
--- a/src/lib/eolian/database_class_api.c
+++ b/src/lib/eolian/database_class_api.c
@@ -70,6 +70,13 @@ eolian_class_description_get(const Eolian_Class *cl)
return cl->description;
}
+EAPI const Eolian_Documentation *
+eolian_class_documentation_get(const Eolian_Class *cl)
+{
+ EINA_SAFETY_ON_NULL_RETURN_VAL(cl, NULL);
+ return cl->doc;
+}
+
EAPI Eina_Stringshare*
eolian_class_legacy_prefix_get(const Eolian_Class *cl)
{
diff --git a/src/lib/eolian/database_event_api.c
b/src/lib/eolian/database_event_api.c
index 26a5167..0a180e4 100644
--- a/src/lib/eolian/database_event_api.c
+++ b/src/lib/eolian/database_event_api.c
@@ -26,6 +26,13 @@ eolian_event_description_get(const Eolian_Event *event)
return event->comment;
}
+EAPI const Eolian_Documentation *
+eolian_event_documentation_get(const Eolian_Event *event)
+{
+ EINA_SAFETY_ON_NULL_RETURN_VAL(event, NULL);
+ return event->doc;
+}
+
EAPI Eolian_Object_Scope
eolian_event_scope_get(const Eolian_Event *event)
{
diff --git a/src/lib/eolian/database_function_api.c
b/src/lib/eolian/database_function_api.c
index 6f646c8..4ff34a7 100644
--- a/src/lib/eolian/database_function_api.c
+++ b/src/lib/eolian/database_function_api.c
@@ -98,6 +98,18 @@ eolian_function_description_get(const Eolian_Function *fid,
Eolian_Function_Type
}
}
+EAPI const Eolian_Documentation *
+eolian_function_documentation_get(const Eolian_Function *fid,
Eolian_Function_Type ftype)
+{
+ EINA_SAFETY_ON_NULL_RETURN_VAL(fid, NULL);
+ switch (ftype)
+ {
+ case EOLIAN_PROP_GET: return fid->get_doc; break;
+ case EOLIAN_PROP_SET: return fid->set_doc; break;
+ default: return fid->common_doc;
+ }
+}
+
EAPI Eina_Bool
eolian_function_is_virtual_pure(const Eolian_Function *fid,
Eolian_Function_Type ftype)
{
@@ -246,6 +258,17 @@ eolian_function_return_comment_get(const Eolian_Function
*fid, Eolian_Function_T
}
}
+EAPI const Eolian_Documentation *
+eolian_function_return_documentation_get(const Eolian_Function *fid,
Eolian_Function_Type ftype)
+{
+ switch (ftype)
+ {
+ case EOLIAN_PROP_SET: return fid->set_return_doc; break;
+ case EOLIAN_UNRESOLVED: case EOLIAN_METHOD: case EOLIAN_PROPERTY: case
EOLIAN_PROP_GET: return fid->get_return_doc; break;
+ default: return NULL;
+ }
+}
+
EAPI Eina_Bool
eolian_function_return_is_warn_unused(const Eolian_Function *fid,
Eolian_Function_Type ftype)
diff --git a/src/lib/eolian/database_function_parameter_api.c
b/src/lib/eolian/database_function_parameter_api.c
index 9a566f8..6c9a8d7 100644
--- a/src/lib/eolian/database_function_parameter_api.c
+++ b/src/lib/eolian/database_function_parameter_api.c
@@ -40,6 +40,13 @@ eolian_parameter_description_get(const
Eolian_Function_Parameter *param)
return param->description;
}
+EAPI const Eolian_Documentation *
+eolian_parameter_documentation_get(const Eolian_Function_Parameter *param)
+{
+ EINA_SAFETY_ON_NULL_RETURN_VAL(param, NULL);
+ return param->doc;
+}
+
EAPI Eina_Bool
eolian_parameter_is_nonull(const Eolian_Function_Parameter *param)
{
diff --git a/src/lib/eolian/database_type_api.c
b/src/lib/eolian/database_type_api.c
index 6ae8935..e1a01bb 100644
--- a/src/lib/eolian/database_type_api.c
+++ b/src/lib/eolian/database_type_api.c
@@ -121,6 +121,13 @@ eolian_type_struct_field_description_get(const
Eolian_Struct_Type_Field *fl)
return fl->comment;
}
+EAPI const Eolian_Documentation *
+eolian_type_struct_field_documentation_get(const Eolian_Struct_Type_Field *fl)
+{
+ EINA_SAFETY_ON_NULL_RETURN_VAL(fl, NULL);
+ return fl->doc;
+}
+
EAPI const Eolian_Type *
eolian_type_struct_field_type_get(const Eolian_Struct_Type_Field *fl)
{
@@ -185,6 +192,13 @@ eolian_type_enum_field_description_get(const
Eolian_Enum_Type_Field *fl)
return fl->comment;
}
+EAPI const Eolian_Documentation *
+eolian_type_enum_field_documentation_get(const Eolian_Enum_Type_Field *fl)
+{
+ EINA_SAFETY_ON_NULL_RETURN_VAL(fl, NULL);
+ return fl->doc;
+}
+
EAPI const Eolian_Expression *
eolian_type_enum_field_value_get(const Eolian_Enum_Type_Field *fl, Eina_Bool
force)
{
@@ -212,6 +226,17 @@ eolian_type_description_get(const Eolian_Type *tp)
return tp->comment;
}
+EAPI const Eolian_Documentation *
+eolian_type_documentation_get(const Eolian_Type *tp)
+{
+ Eolian_Type_Type tpp;
+ EINA_SAFETY_ON_NULL_RETURN_VAL(tp, NULL);
+ tpp = eolian_type_type_get(tp);
+ EINA_SAFETY_ON_FALSE_RETURN_VAL(tpp != EOLIAN_TYPE_POINTER
+ && tpp != EOLIAN_TYPE_VOID, NULL);
+ return tp->doc;
+}
+
EAPI Eina_Stringshare *
eolian_type_file_get(const Eolian_Type *tp)
{
diff --git a/src/lib/eolian/database_var_api.c
b/src/lib/eolian/database_var_api.c
index cb473a3..45400f5 100644
--- a/src/lib/eolian/database_var_api.c
+++ b/src/lib/eolian/database_var_api.c
@@ -61,6 +61,13 @@ eolian_variable_description_get(const Eolian_Variable *var)
return var->comment;
}
+EAPI const Eolian_Documentation *
+eolian_variable_documentation_get(const Eolian_Variable *var)
+{
+ EINA_SAFETY_ON_NULL_RETURN_VAL(var, NULL);
+ return var->doc;
+}
+
EAPI Eina_Stringshare *
eolian_variable_file_get(const Eolian_Variable *var)
{
diff --git a/src/lib/eolian/eolian_database.c b/src/lib/eolian/eolian_database.c
index b0c4ab4..cc23f87 100644
--- a/src/lib/eolian/eolian_database.c
+++ b/src/lib/eolian/eolian_database.c
@@ -169,6 +169,20 @@ void database_doc_del(Eolian_Documentation *doc)
free(doc);
}
+EAPI Eina_Stringshare *
+eolian_documentation_summary_get(const Eolian_Documentation *doc)
+{
+ EINA_SAFETY_ON_NULL_RETURN_VAL(doc, NULL);
+ return doc->summary;
+}
+
+EAPI Eina_Stringshare *
+eolian_documentation_description_get(const Eolian_Documentation *doc)
+{
+ EINA_SAFETY_ON_NULL_RETURN_VAL(doc, NULL);
+ return doc->description;
+}
+
#define EO_SUFFIX ".eo"
#define EOT_SUFFIX ".eot"
diff --git a/src/tests/eolian/data/docs.eo b/src/tests/eolian/data/docs.eo
index 36d1c8f..c219ced 100644
--- a/src/tests/eolian/data/docs.eo
+++ b/src/tests/eolian/data/docs.eo
@@ -2,6 +2,8 @@ struct Foo {
[[This is struct Foo.
This is a longer description for struct Foo.
+
+ This is another paragraph.
]]
field1: int; [[Field documentation.]]
field2: float;
diff --git a/src/tests/eolian/eolian_parsing.c
b/src/tests/eolian/eolian_parsing.c
index f3d86a5..8b8503b 100644
--- a/src/tests/eolian/eolian_parsing.c
+++ b/src/tests/eolian/eolian_parsing.c
@@ -1130,12 +1130,154 @@ END_TEST
START_TEST(eolian_docs)
{
+ const Eolian_Type *type;
+ const Eolian_Class *class;
+ const Eolian_Event *event;
+ const Eolian_Variable *var;
+ const Eolian_Function *fid;
+ const Eolian_Documentation *doc;
+ const Eolian_Function_Parameter *par;
+ const Eolian_Struct_Type_Field *sfl;
+ const Eolian_Enum_Type_Field *efl;
+ Eina_Iterator *itr;
+
eolian_init();
fail_if(!eolian_directory_scan(PACKAGE_DATA_DIR"/data"));
fail_if(!eolian_file_parse(PACKAGE_DATA_DIR"/data/docs.eo"));
- fail_if(!eolian_class_get_by_name("Docs"));
+
+ fail_if(!(type = eolian_type_struct_get_by_name("Foo")));
+ fail_if(!(doc = eolian_type_documentation_get(type)));
+ fail_if(strcmp(eolian_documentation_summary_get(doc),
+ "This is struct Foo."));
+ fail_if(strcmp(eolian_documentation_description_get(doc),
+ "This is a longer description for struct Foo.\n\n"
+ "This is another paragraph."));
+
+ fail_if(!(sfl = eolian_type_struct_field_get(type, "field1")));
+ fail_if(!(doc = eolian_type_struct_field_documentation_get(sfl)));
+ fail_if(strcmp(eolian_documentation_summary_get(doc),
+ "Field documentation."));
+ fail_if(eolian_documentation_description_get(doc));
+
+ fail_if(!(sfl = eolian_type_struct_field_get(type, "field2")));
+ fail_if(eolian_type_struct_field_documentation_get(sfl));
+
+ fail_if(!(sfl = eolian_type_struct_field_get(type, "field3")));
+ fail_if(!(doc = eolian_type_struct_field_documentation_get(sfl)));
+ fail_if(strcmp(eolian_documentation_summary_get(doc),
+ "Another field documentation."));
+ fail_if(eolian_documentation_description_get(doc));
+
+ fail_if(!(type = eolian_type_enum_get_by_name("Bar")));
+ fail_if(!(doc = eolian_type_documentation_get(type)));
+ fail_if(strcmp(eolian_documentation_summary_get(doc),
+ "Docs for enum Bar."));
+ fail_if(eolian_documentation_description_get(doc));
+
+ fail_if(!(efl = eolian_type_enum_field_get(type, "blah")));
+ fail_if(eolian_type_enum_field_documentation_get(efl));
+
+ fail_if(!(efl = eolian_type_enum_field_get(type, "foo")));
+ fail_if(!(doc = eolian_type_enum_field_documentation_get(efl)));
+ fail_if(strcmp(eolian_documentation_summary_get(doc),
+ "Docs for foo."));
+ fail_if(eolian_documentation_description_get(doc));
+
+ fail_if(!(efl = eolian_type_enum_field_get(type, "bar")));
+ fail_if(!(doc = eolian_type_enum_field_documentation_get(efl)));
+ fail_if(strcmp(eolian_documentation_summary_get(doc),
+ "Docs for bar."));
+ fail_if(eolian_documentation_description_get(doc));
+
+ fail_if(!(type = eolian_type_alias_get_by_name("Alias")));
+ fail_if(!(doc = eolian_type_documentation_get(type)));
+ fail_if(strcmp(eolian_documentation_summary_get(doc),
+ "Docs for typedef."));
+ fail_if(strcmp(eolian_documentation_description_get(doc),
+ "More docs for typedef. See @Bar."));
+
+ fail_if(!(var = eolian_variable_global_get_by_name("pants")));
+ fail_if(!(doc = eolian_variable_documentation_get(var)));
+ fail_if(strcmp(eolian_documentation_summary_get(doc),
+ "Docs for var."));
+ fail_if(eolian_documentation_description_get(doc));
+
+ fail_if(!(type = eolian_type_struct_get_by_name("Opaque")));
+ fail_if(!(doc = eolian_type_documentation_get(type)));
+ fail_if(strcmp(eolian_documentation_summary_get(doc),
+ "Opaque struct docs. See @Foo for another struct."));
+ fail_if(eolian_documentation_description_get(doc));
+
+ fail_if(!(class = eolian_class_get_by_name("Docs")));
+ fail_if(!(doc = eolian_class_documentation_get(class)));
+ fail_if(strcmp(eolian_documentation_summary_get(doc),
+ "Docs for class."));
+ fail_if(strcmp(eolian_documentation_description_get(doc),
+ "More docs for class. @Foo @Bar @Alias @pants"));
+
+ fail_if(!(fid = eolian_class_function_get_by_name(class, "meth",
EOLIAN_METHOD)));
+ fail_if(!(doc = eolian_function_documentation_get(fid, EOLIAN_METHOD)));
+ fail_if(strcmp(eolian_documentation_summary_get(doc),
+ "Method documentation."));
+ fail_if(eolian_documentation_description_get(doc));
+
+ fail_if(!(itr = eolian_function_parameters_get(fid)));
+
+ fail_if(!eina_iterator_next(itr, (void**)&par));
+ fail_if(!(doc = eolian_parameter_documentation_get(par)));
+ fail_if(strcmp(eolian_documentation_summary_get(doc),
+ "Param documentation."));
+ fail_if(eolian_documentation_description_get(doc));
+
+ fail_if(!eina_iterator_next(itr, (void**)&par));
+ fail_if(eolian_parameter_documentation_get(par));
+
+ fail_if(!eina_iterator_next(itr, (void**)&par));
+ fail_if(!(doc = eolian_parameter_documentation_get(par)));
+ fail_if(strcmp(eolian_documentation_summary_get(doc),
+ "Another param documentation."));
+ fail_if(eolian_documentation_description_get(doc));
+
+ fail_if(eina_iterator_next(itr, (void**)&par));
+ eina_iterator_free(itr);
+
+ fail_if(!(doc = eolian_function_return_documentation_get(fid,
EOLIAN_METHOD)));
+ fail_if(strcmp(eolian_documentation_summary_get(doc),
+ "Return documentation."));
+ fail_if(eolian_documentation_description_get(doc));
+
+ fail_if(!(fid = eolian_class_function_get_by_name(class, "prop",
EOLIAN_PROPERTY)));
+ fail_if(!(doc = eolian_function_documentation_get(fid, EOLIAN_PROPERTY)));
+ fail_if(strcmp(eolian_documentation_summary_get(doc),
+ "Property common documentation."));
+ fail_if(eolian_documentation_description_get(doc));
+ fail_if(!(doc = eolian_function_documentation_get(fid, EOLIAN_PROP_GET)));
+ fail_if(strcmp(eolian_documentation_summary_get(doc),
+ "Get documentation."));
+ fail_if(eolian_documentation_description_get(doc));
+ fail_if(!(doc = eolian_function_documentation_get(fid, EOLIAN_PROP_SET)));
+ fail_if(strcmp(eolian_documentation_summary_get(doc),
+ "Set documentation."));
+ fail_if(eolian_documentation_description_get(doc));
+
+ fail_if(!(itr = eolian_property_values_get(fid, EOLIAN_PROP_GET)));
+
+ fail_if(!eina_iterator_next(itr, (void**)&par));
+ fail_if(!(doc = eolian_parameter_documentation_get(par)));
+ fail_if(strcmp(eolian_documentation_summary_get(doc),
+ "Value documentation."));
+ fail_if(eolian_documentation_description_get(doc));
+
+ fail_if(eina_iterator_next(itr, (void**)&par));
+ eina_iterator_free(itr);
+
+ fail_if(!(event = eolian_class_event_get_by_name(class, "clicked")));
+ fail_if(!(doc = eolian_event_documentation_get(event)));
+ fail_if(strcmp(eolian_documentation_summary_get(doc),
+ "Event docs."));
+ fail_if(eolian_documentation_description_get(doc));
eolian_shutdown();
}
--
