forked from enlightenment/efl
csharp: Fix build and doc generation re beta stuff
Summary: When skipping beta items, make sure generated documentation does not try to refer to beta stuff using `see` tags. Doing so would lead to warnings when generating the xml doc file and as we now treat warnings as errors, compilation would fail. Instead of `see` tags, use a simple `span` with a suffix text explaining said item is beta. Reviewers: vitor.sousa, felipealmeida, segfaultxavi Reviewed By: segfaultxavi Subscribers: cedric, #reviewers, #committers Tags: #efl, #expertise_solutions Differential Revision: https://phab.enlightenment.org/D9258
This commit is contained in:
parent
2baad6ac68
commit
15e5d29f88
|
@ -11,6 +11,8 @@
|
||||||
|
|
||||||
#include <Eina.h>
|
#include <Eina.h>
|
||||||
|
|
||||||
|
static const std::string BETA_REF_SUFFIX = " (object still in beta stage)";
|
||||||
|
|
||||||
namespace eolian_mono {
|
namespace eolian_mono {
|
||||||
|
|
||||||
struct documentation_generator
|
struct documentation_generator
|
||||||
|
@ -128,32 +130,38 @@ struct documentation_generator
|
||||||
}
|
}
|
||||||
|
|
||||||
// Turns an Eolian reference like @Efl.Input.Pointer.tool into a <see> tag
|
// Turns an Eolian reference like @Efl.Input.Pointer.tool into a <see> tag
|
||||||
static std::string ref_conversion(const ::Eolian_Doc_Token *token, const Eolian_State *state, std::string name_tail)
|
static std::string ref_conversion(const ::Eolian_Doc_Token *token, const Eolian_State *state, std::string name_tail,
|
||||||
|
bool want_beta)
|
||||||
{
|
{
|
||||||
const Eolian_Object *data, *data2;
|
const Eolian_Object *data, *data2;
|
||||||
::Eolian_Object_Type type =
|
::Eolian_Object_Type type =
|
||||||
::eolian_doc_token_ref_resolve(token, state, &data, &data2);
|
::eolian_doc_token_ref_resolve(token, state, &data, &data2);
|
||||||
std::string ref;
|
std::string ref;
|
||||||
|
bool is_beta = false;
|
||||||
switch(type)
|
switch(type)
|
||||||
{
|
{
|
||||||
case ::EOLIAN_OBJECT_STRUCT_FIELD:
|
case ::EOLIAN_OBJECT_STRUCT_FIELD:
|
||||||
ref = name_helpers::managed_namespace(::eolian_object_name_get(data));
|
ref = name_helpers::managed_namespace(::eolian_object_name_get(data));
|
||||||
ref += ".";
|
ref += ".";
|
||||||
ref += ::eolian_object_name_get(data2);
|
ref += ::eolian_object_name_get(data2);
|
||||||
|
is_beta = eolian_object_is_beta(data) || eolian_object_is_beta(data2);
|
||||||
if (blacklist::is_struct_blacklisted(ref)) return "";
|
if (blacklist::is_struct_blacklisted(ref)) return "";
|
||||||
break;
|
break;
|
||||||
case ::EOLIAN_OBJECT_EVENT:
|
case ::EOLIAN_OBJECT_EVENT:
|
||||||
ref = object_ref_conversion(data);
|
ref = object_ref_conversion(data);
|
||||||
ref += ".";
|
ref += ".";
|
||||||
ref += name_helpers::managed_event_name(::eolian_object_name_get(data2));
|
ref += name_helpers::managed_event_name(::eolian_object_name_get(data2));
|
||||||
|
is_beta = eolian_object_is_beta(data) || eolian_object_is_beta(data2);
|
||||||
break;
|
break;
|
||||||
case ::EOLIAN_OBJECT_ENUM_FIELD:
|
case ::EOLIAN_OBJECT_ENUM_FIELD:
|
||||||
ref = name_helpers::managed_namespace(::eolian_object_name_get(data));
|
ref = name_helpers::managed_namespace(::eolian_object_name_get(data));
|
||||||
ref += ".";
|
ref += ".";
|
||||||
ref += name_helpers::enum_field_managed_name(::eolian_object_name_get(data2));
|
ref += name_helpers::enum_field_managed_name(::eolian_object_name_get(data2));
|
||||||
|
is_beta = eolian_object_is_beta(data) || eolian_object_is_beta(data2);
|
||||||
break;
|
break;
|
||||||
case ::EOLIAN_OBJECT_FUNCTION:
|
case ::EOLIAN_OBJECT_FUNCTION:
|
||||||
ref += function_conversion(data, (const ::Eolian_Function *)data2, name_tail);
|
ref += function_conversion(data, (const ::Eolian_Function *)data2, name_tail);
|
||||||
|
is_beta = eolian_object_is_beta(data) || eolian_object_is_beta(data2);
|
||||||
break;
|
break;
|
||||||
case ::EOLIAN_OBJECT_VARIABLE:
|
case ::EOLIAN_OBJECT_VARIABLE:
|
||||||
if (::eolian_variable_type_get((::Eolian_Variable *)data) == ::EOLIAN_VAR_CONSTANT)
|
if (::eolian_variable_type_get((::Eolian_Variable *)data) == ::EOLIAN_VAR_CONSTANT)
|
||||||
|
@ -173,16 +181,21 @@ struct documentation_generator
|
||||||
break;
|
break;
|
||||||
case ::EOLIAN_OBJECT_CLASS:
|
case ::EOLIAN_OBJECT_CLASS:
|
||||||
ref = object_ref_conversion(data);
|
ref = object_ref_conversion(data);
|
||||||
|
is_beta = eolian_object_is_beta(data);
|
||||||
break;
|
break;
|
||||||
default:
|
default:
|
||||||
ref = name_helpers::managed_namespace(::eolian_object_name_get(data));
|
ref = name_helpers::managed_namespace(::eolian_object_name_get(data));
|
||||||
|
is_beta = eolian_object_is_beta(data);
|
||||||
break;
|
break;
|
||||||
}
|
}
|
||||||
|
|
||||||
|
if (!ref.empty() && !want_beta && is_beta)
|
||||||
|
ref += BETA_REF_SUFFIX;
|
||||||
return ref;
|
return ref;
|
||||||
}
|
}
|
||||||
|
|
||||||
// Turns EO documentation syntax into C# triple-slash XML comment syntax
|
// Turns EO documentation syntax into C# triple-slash XML comment syntax
|
||||||
static std::string syntax_conversion(std::string text, const Eolian_State *state)
|
static std::string syntax_conversion(std::string text, const Eolian_State *state, bool want_beta)
|
||||||
{
|
{
|
||||||
std::string new_text, ref;
|
std::string new_text, ref;
|
||||||
::Eolian_Doc_Token token;
|
::Eolian_Doc_Token token;
|
||||||
|
@ -213,9 +226,14 @@ struct documentation_generator
|
||||||
new_text += token_text;
|
new_text += token_text;
|
||||||
break;
|
break;
|
||||||
case ::EOLIAN_DOC_TOKEN_REF:
|
case ::EOLIAN_DOC_TOKEN_REF:
|
||||||
ref = ref_conversion(&token, state, name_tail);
|
ref = ref_conversion(&token, state, name_tail, want_beta);
|
||||||
if (ref != "")
|
if (ref != "")
|
||||||
new_text += "<see cref=\"" + ref + "\"/>";
|
{
|
||||||
|
if (utils::ends_with(ref, BETA_REF_SUFFIX))
|
||||||
|
new_text += "<span class=\"text-muted\">" + ref + "</span>";
|
||||||
|
else
|
||||||
|
new_text += "<see cref=\"" + ref + "\"/>";
|
||||||
|
}
|
||||||
else
|
else
|
||||||
// Unresolved references are passed through.
|
// Unresolved references are passed through.
|
||||||
// They will appear in the docs as plain text, without link,
|
// They will appear in the docs as plain text, without link,
|
||||||
|
@ -264,7 +282,8 @@ struct documentation_generator
|
||||||
std::string new_text;
|
std::string new_text;
|
||||||
if (!as_generator(html_escaped_string).generate(std::back_inserter(new_text), text, context))
|
if (!as_generator(html_escaped_string).generate(std::back_inserter(new_text), text, context))
|
||||||
return false;
|
return false;
|
||||||
new_text = syntax_conversion( new_text, context_find_tag<eolian_state_context>(context).state );
|
auto options = context_find_tag<options_context>(context);
|
||||||
|
new_text = syntax_conversion( new_text, context_find_tag<eolian_state_context>(context).state, options.want_beta);
|
||||||
|
|
||||||
std::string tabs;
|
std::string tabs;
|
||||||
as_generator(scope_tab(scope_size) << "/// ").generate (std::back_inserter(tabs), attributes::unused, context);
|
as_generator(scope_tab(scope_size) << "/// ").generate (std::back_inserter(tabs), attributes::unused, context);
|
||||||
|
@ -486,8 +505,18 @@ struct documentation_generator
|
||||||
|
|
||||||
for (auto &¶m : ctor.function.parameters)
|
for (auto &¶m : ctor.function.parameters)
|
||||||
{
|
{
|
||||||
|
auto ref = function_conversion(func);
|
||||||
|
|
||||||
|
if (!context_find_tag<options_context>(context).want_beta && func.is_beta)
|
||||||
|
{
|
||||||
|
ref += BETA_REF_SUFFIX;
|
||||||
|
ref = "<span class=\"text-muted\">" + ref + "</span>";
|
||||||
|
}
|
||||||
|
else
|
||||||
|
ref = "<see cref=\"" + ref + "\" />";
|
||||||
|
|
||||||
if (!as_generator(
|
if (!as_generator(
|
||||||
scope_tab << "/// <param name=\"" << constructor_parameter_name(ctor) << "\">" << summary << " See <see cref=\"" << function_conversion(func) << "\"/></param>\n"
|
scope_tab << "/// <param name=\"" << constructor_parameter_name(ctor) << "\">" << summary << " See " << ref << "</param>\n"
|
||||||
).generate(sink, param, context))
|
).generate(sink, param, context))
|
||||||
return false;
|
return false;
|
||||||
}
|
}
|
||||||
|
|
Loading…
Reference in New Issue