bu5hm4n
/
efl
forked from enlightenment/efl
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

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
This commit is contained in:
Daniel Kolesa 2015-06-03 16:16:53 +01:00
parent a867caf260
commit ba033a4cfc
10 changed files with 356 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

121
src/lib/eolian/Eolian.h
View File

@ -700,6 +700,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
*
@ -830,6 +840,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.
*
@ -1008,6 +1029,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.
*
@ -1082,6 +1113,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.
*
@ -1315,6 +1360,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
*
@ -1520,6 +1575,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.
*
@ -1587,6 +1652,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.
*
@ -1624,6 +1699,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.
*
@ -1992,6 +2078,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.
*
@ -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
/**

7
src/lib/eolian/database_class_api.c
View File

@ -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)
{

7
src/lib/eolian/database_event_api.c
View File

@ -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)
{

23
src/lib/eolian/database_function_api.c
View File

@ -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)

7
src/lib/eolian/database_function_parameter_api.c
View File

@ -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)
{

25
src/lib/eolian/database_type_api.c
View File

@ -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)
{

7
src/lib/eolian/database_var_api.c
View File

@ -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)
{

14
src/lib/eolian/eolian_database.c
View File

@ -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"

2
src/tests/eolian/data/docs.eo
View File

@ -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;

144
src/tests/eolian/eolian_parsing.c
View File

@ -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();
}