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

10 files changed, 356 insertions, 1 deletions

diff --git a/src/lib/eolian/Eolian.h b/src/lib/eolian/Eolian.h
index 8f74460545..c749beb73c 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 e4c9723095..ae7497781c 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 26a516753a..0a180e4878 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 6f646c847f..4ff34a7813 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 9a566f826d..6c9a8d7426 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 6ae8935a72..e1a01bbdbd 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 cb473a3c08..45400f5c6b 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 b0c4ab44b5..cc23f87d6b 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 36d1c8f62d..c219cedbe5 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 f3d86a543b..8b8503b086 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();
 }