summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorLauro Moura <lauromoura@expertisesolutions.com.br>2019-07-11 10:19:52 +0200
committerXavi Artigas <xavierartigas@yahoo.es>2019-07-11 10:19:52 +0200
commit15e5d29f886b296ce2e0d084367e529f550c3307 (patch)
tree74392851183f10bbdfa3e6b8e76bb0600fbcb6d5
parent2baad6ac68f174e12e6c387f183285467cef6dab (diff)
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
-rw-r--r--src/bin/eolian_mono/eolian/mono/documentation.hh41
1 files changed, 35 insertions, 6 deletions
diff --git a/src/bin/eolian_mono/eolian/mono/documentation.hh b/src/bin/eolian_mono/eolian/mono/documentation.hh
index ac072a4220..a672d209b4 100644
--- a/src/bin/eolian_mono/eolian/mono/documentation.hh
+++ b/src/bin/eolian_mono/eolian/mono/documentation.hh
@@ -11,6 +11,8 @@
11 11
12#include <Eina.h> 12#include <Eina.h>
13 13
14static const std::string BETA_REF_SUFFIX = " (object still in beta stage)";
15
14namespace eolian_mono { 16namespace eolian_mono {
15 17
16struct documentation_generator 18struct documentation_generator
@@ -128,32 +130,38 @@ struct documentation_generator
128 } 130 }
129 131
130 // Turns an Eolian reference like @Efl.Input.Pointer.tool into a <see> tag 132 // Turns an Eolian reference like @Efl.Input.Pointer.tool into a <see> tag
131 static std::string ref_conversion(const ::Eolian_Doc_Token *token, const Eolian_State *state, std::string name_tail) 133 static std::string ref_conversion(const ::Eolian_Doc_Token *token, const Eolian_State *state, std::string name_tail,
134 bool want_beta)
132 { 135 {
133 const Eolian_Object *data, *data2; 136 const Eolian_Object *data, *data2;
134 ::Eolian_Object_Type type = 137 ::Eolian_Object_Type type =
135 ::eolian_doc_token_ref_resolve(token, state, &data, &data2); 138 ::eolian_doc_token_ref_resolve(token, state, &data, &data2);
136 std::string ref; 139 std::string ref;
140 bool is_beta = false;
137 switch(type) 141 switch(type)
138 { 142 {
139 case ::EOLIAN_OBJECT_STRUCT_FIELD: 143 case ::EOLIAN_OBJECT_STRUCT_FIELD:
140 ref = name_helpers::managed_namespace(::eolian_object_name_get(data)); 144 ref = name_helpers::managed_namespace(::eolian_object_name_get(data));
141 ref += "."; 145 ref += ".";
142 ref += ::eolian_object_name_get(data2); 146 ref += ::eolian_object_name_get(data2);
147 is_beta = eolian_object_is_beta(data) || eolian_object_is_beta(data2);
143 if (blacklist::is_struct_blacklisted(ref)) return ""; 148 if (blacklist::is_struct_blacklisted(ref)) return "";
144 break; 149 break;
145 case ::EOLIAN_OBJECT_EVENT: 150 case ::EOLIAN_OBJECT_EVENT:
146 ref = object_ref_conversion(data); 151 ref = object_ref_conversion(data);
147 ref += "."; 152 ref += ".";
148 ref += name_helpers::managed_event_name(::eolian_object_name_get(data2)); 153 ref += name_helpers::managed_event_name(::eolian_object_name_get(data2));
154 is_beta = eolian_object_is_beta(data) || eolian_object_is_beta(data2);
149 break; 155 break;
150 case ::EOLIAN_OBJECT_ENUM_FIELD: 156 case ::EOLIAN_OBJECT_ENUM_FIELD:
151 ref = name_helpers::managed_namespace(::eolian_object_name_get(data)); 157 ref = name_helpers::managed_namespace(::eolian_object_name_get(data));
152 ref += "."; 158 ref += ".";
153 ref += name_helpers::enum_field_managed_name(::eolian_object_name_get(data2)); 159 ref += name_helpers::enum_field_managed_name(::eolian_object_name_get(data2));
160 is_beta = eolian_object_is_beta(data) || eolian_object_is_beta(data2);
154 break; 161 break;
155 case ::EOLIAN_OBJECT_FUNCTION: 162 case ::EOLIAN_OBJECT_FUNCTION:
156 ref += function_conversion(data, (const ::Eolian_Function *)data2, name_tail); 163 ref += function_conversion(data, (const ::Eolian_Function *)data2, name_tail);
164 is_beta = eolian_object_is_beta(data) || eolian_object_is_beta(data2);
157 break; 165 break;
158 case ::EOLIAN_OBJECT_VARIABLE: 166 case ::EOLIAN_OBJECT_VARIABLE:
159 if (::eolian_variable_type_get((::Eolian_Variable *)data) == ::EOLIAN_VAR_CONSTANT) 167 if (::eolian_variable_type_get((::Eolian_Variable *)data) == ::EOLIAN_VAR_CONSTANT)
@@ -173,16 +181,21 @@ struct documentation_generator
173 break; 181 break;
174 case ::EOLIAN_OBJECT_CLASS: 182 case ::EOLIAN_OBJECT_CLASS:
175 ref = object_ref_conversion(data); 183 ref = object_ref_conversion(data);
184 is_beta = eolian_object_is_beta(data);
176 break; 185 break;
177 default: 186 default:
178 ref = name_helpers::managed_namespace(::eolian_object_name_get(data)); 187 ref = name_helpers::managed_namespace(::eolian_object_name_get(data));
188 is_beta = eolian_object_is_beta(data);
179 break; 189 break;
180 } 190 }
191
192 if (!ref.empty() && !want_beta && is_beta)
193 ref += BETA_REF_SUFFIX;
181 return ref; 194 return ref;
182 } 195 }
183 196
184 // Turns EO documentation syntax into C# triple-slash XML comment syntax 197 // Turns EO documentation syntax into C# triple-slash XML comment syntax
185 static std::string syntax_conversion(std::string text, const Eolian_State *state) 198 static std::string syntax_conversion(std::string text, const Eolian_State *state, bool want_beta)
186 { 199 {
187 std::string new_text, ref; 200 std::string new_text, ref;
188 ::Eolian_Doc_Token token; 201 ::Eolian_Doc_Token token;
@@ -213,9 +226,14 @@ struct documentation_generator
213 new_text += token_text; 226 new_text += token_text;
214 break; 227 break;
215 case ::EOLIAN_DOC_TOKEN_REF: 228 case ::EOLIAN_DOC_TOKEN_REF:
216 ref = ref_conversion(&token, state, name_tail); 229 ref = ref_conversion(&token, state, name_tail, want_beta);
217 if (ref != "") 230 if (ref != "")
218 new_text += "<see cref=\"" + ref + "\"/>"; 231 {
232 if (utils::ends_with(ref, BETA_REF_SUFFIX))
233 new_text += "<span class=\"text-muted\">" + ref + "</span>";
234 else
235 new_text += "<see cref=\"" + ref + "\"/>";
236 }
219 else 237 else
220 // Unresolved references are passed through. 238 // Unresolved references are passed through.
221 // They will appear in the docs as plain text, without link, 239 // They will appear in the docs as plain text, without link,
@@ -264,7 +282,8 @@ struct documentation_generator
264 std::string new_text; 282 std::string new_text;
265 if (!as_generator(html_escaped_string).generate(std::back_inserter(new_text), text, context)) 283 if (!as_generator(html_escaped_string).generate(std::back_inserter(new_text), text, context))
266 return false; 284 return false;
267 new_text = syntax_conversion( new_text, context_find_tag<eolian_state_context>(context).state ); 285 auto options = context_find_tag<options_context>(context);
286 new_text = syntax_conversion( new_text, context_find_tag<eolian_state_context>(context).state, options.want_beta);
268 287
269 std::string tabs; 288 std::string tabs;
270 as_generator(scope_tab(scope_size) << "/// ").generate (std::back_inserter(tabs), attributes::unused, context); 289 as_generator(scope_tab(scope_size) << "/// ").generate (std::back_inserter(tabs), attributes::unused, context);
@@ -486,8 +505,18 @@ struct documentation_generator
486 505
487 for (auto &&param : ctor.function.parameters) 506 for (auto &&param : ctor.function.parameters)
488 { 507 {
508 auto ref = function_conversion(func);
509
510 if (!context_find_tag<options_context>(context).want_beta && func.is_beta)
511 {
512 ref += BETA_REF_SUFFIX;
513 ref = "<span class=\"text-muted\">" + ref + "</span>";
514 }
515 else
516 ref = "<see cref=\"" + ref + "\" />";
517
489 if (!as_generator( 518 if (!as_generator(
490 scope_tab << "/// <param name=\"" << constructor_parameter_name(ctor) << "\">" << summary << " See <see cref=\"" << function_conversion(func) << "\"/></param>\n" 519 scope_tab << "/// <param name=\"" << constructor_parameter_name(ctor) << "\">" << summary << " See " << ref << "</param>\n"
491 ).generate(sink, param, context)) 520 ).generate(sink, param, context))
492 return false; 521 return false;
493 } 522 }