summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorXavi Artigas <xavierartigas@yahoo.es>2019-12-12 19:00:38 -0300
committerLauro Moura <lauromoura@expertisesolutions.com.br>2019-12-12 19:07:59 -0300
commitbd0231e98b00faf9b3591b74cfbb9e1a982d2d00 (patch)
tree202f2a38eb2decf032d3135aae1d5cb42e8acbcb
parentca3a9133757841b0bfb65cd5862ac5ea0886626e (diff)
eolian_mono: proper parsing of doc notes and paragraphs
Summary: The documentation tokenizer relies on proper separation of paragraphs, and we were not doing that. This fixes detection of Note:, Warning:, Remark: and TODO: tags. Additionally, we were removing the blank line between the summary and the description, artificially joining them. Test Plan: Everything builds and passes tests, and docs with `Note:` tags are correctly rendered (like `Efl.Loop_Consumer.new_promise`, for example) Reviewers: lauromoura Reviewed By: lauromoura Subscribers: cedric, #reviewers, #committers Tags: #efl Differential Revision: https://phab.enlightenment.org/D10868
-rw-r--r--src/bin/eolian_mono/eolian/mono/documentation.hh130
-rw-r--r--src/lib/eolian_cxx/grammar/klass_def.hpp3
2 files changed, 75 insertions, 58 deletions
diff --git a/src/bin/eolian_mono/eolian/mono/documentation.hh b/src/bin/eolian_mono/eolian/mono/documentation.hh
index 2370829..d009e45 100644
--- a/src/bin/eolian_mono/eolian/mono/documentation.hh
+++ b/src/bin/eolian_mono/eolian/mono/documentation.hh
@@ -230,68 +230,84 @@ struct documentation_generator
230 static std::string syntax_conversion(std::string text, const Eolian_State *state, bool want_beta) 230 static std::string syntax_conversion(std::string text, const Eolian_State *state, bool want_beta)
231 { 231 {
232 std::string new_text, ref; 232 std::string new_text, ref;
233 ::Eolian_Doc_Token token;
234 const char *text_ptr = text.c_str();
235 ::eolian_doc_token_init(&token);
236 ::Eolian_Doc_Token_Type previous_token_type = ::EOLIAN_DOC_TOKEN_UNKNOWN; 233 ::Eolian_Doc_Token_Type previous_token_type = ::EOLIAN_DOC_TOKEN_UNKNOWN;
237 while ((text_ptr = ::eolian_documentation_tokenize(text_ptr, &token)) != NULL) 234 ::Eina_List *paragraphs = ::eolian_documentation_string_split(text.c_str());
235 if (!paragraphs) return new_text;
236 ::Eina_List *data = paragraphs;
237 // For every paragraph
238 do
238 { 239 {
239 std::string token_text, name_tail; 240 char *par = (char *)::eina_list_data_get(data);
240 char *token_text_cstr = ::eolian_doc_token_text_get(&token); 241 const char *text_ptr = par;
241 if (token_text_cstr) 242 ::Eolian_Doc_Token token;
243 ::eolian_doc_token_init(&token);
244 // For every token inside the paragraph
245 while ((text_ptr = ::eolian_documentation_tokenize(text_ptr, &token)) != NULL)
242 { 246 {
243 token_text = token_text_cstr; 247 std::string token_text, name_tail;
244 free(token_text_cstr); 248 char *token_text_cstr = ::eolian_doc_token_text_get(&token);
245 if (token_text.length() > 4) 249 if (token_text_cstr)
246 name_tail = token_text.substr(token_text.length() - 4, 4);
247 }
248 ::Eolian_Doc_Token_Type token_type = ::eolian_doc_token_type_get(&token);
249 switch(token_type)
250 {
251 case ::EOLIAN_DOC_TOKEN_TEXT:
252 // If previous token was a reference and this text token starts with
253 // parentheses, remove them, since the reference will be rendered
254 // with the parentheses already.
255 if ((previous_token_type == ::EOLIAN_DOC_TOKEN_REF) &&
256 (token_text.substr(0, 2) == "()"))
257 token_text = token_text.substr(2, token_text.length() - 2);
258 new_text += token_text;
259 break;
260 case ::EOLIAN_DOC_TOKEN_REF:
261 ref = ref_conversion(&token, state, name_tail, want_beta);
262 if (ref != "")
263 { 250 {
264 if (utils::ends_with(ref, BETA_REF_SUFFIX)) 251 token_text = token_text_cstr;
265 new_text += "<span class=\"text-muted\">" + ref + "</span>"; 252 free(token_text_cstr);
266 else 253 if (token_text.length() > 4)
267 new_text += "<see cref=\"" + ref + "\"/>"; 254 name_tail = token_text.substr(token_text.length() - 4, 4);
268 } 255 }
269 else 256 ::Eolian_Doc_Token_Type token_type = ::eolian_doc_token_type_get(&token);
270 // Unresolved references are passed through. 257 switch(token_type)
271 // They will appear in the docs as plain text, without link, 258 {
272 // but at least they won't be removed by DocFX. 259 case ::EOLIAN_DOC_TOKEN_TEXT:
273 new_text += token_text; 260 // If previous token was a reference and this text token starts with
274 break; 261 // parentheses, remove them, since the reference will be rendered
275 case ::EOLIAN_DOC_TOKEN_MARK_NOTE: 262 // with the parentheses already.
276 new_text += "<b>NOTE:</b>" + token_text.substr(5, token_text.length() - 5); 263 if ((previous_token_type == ::EOLIAN_DOC_TOKEN_REF) &&
277 break; 264 (token_text.substr(0, 2) == "()"))
278 case ::EOLIAN_DOC_TOKEN_MARK_WARNING: 265 token_text = token_text.substr(2, token_text.length() - 2);
279 new_text += "<b>WARNING:</b>" + token_text.substr(8, token_text.length() - 8); 266 new_text += token_text;
280 break; 267 break;
281 case ::EOLIAN_DOC_TOKEN_MARK_REMARK: 268 case ::EOLIAN_DOC_TOKEN_REF:
282 new_text += "<b>REMARK:</b>" + token_text.substr(7, token_text.length() - 7); 269 ref = ref_conversion(&token, state, name_tail, want_beta);
283 break; 270 if (ref != "")
284 case ::EOLIAN_DOC_TOKEN_MARK_TODO: 271 {
285 new_text += "<b>TODO:</b>" + token_text.substr(5, token_text.length() - 5); 272 if (utils::ends_with(ref, BETA_REF_SUFFIX))
286 break; 273 new_text += "<span class=\"text-muted\">" + ref + "</span>";
287 case ::EOLIAN_DOC_TOKEN_MARKUP_MONOSPACE: 274 else
288 new_text += "<c>" + token_text + "</c>"; 275 new_text += "<see cref=\"" + ref + "\"/>";
289 break; 276 }
290 default: 277 else
291 break; 278 // Unresolved references are passed through.
292 } 279 // They will appear in the docs as plain text, without link,
293 previous_token_type = token_type; 280 // but at least they won't be removed by DocFX.
294 } 281 new_text += token_text;
282 break;
283 case ::EOLIAN_DOC_TOKEN_MARK_NOTE:
284 new_text += "<b>NOTE: </b>";
285 break;
286 case ::EOLIAN_DOC_TOKEN_MARK_WARNING:
287 new_text += "<b>WARNING: </b>";
288 break;
289 case ::EOLIAN_DOC_TOKEN_MARK_REMARK:
290 new_text += "<b>REMARK: </b>";
291 break;
292 case ::EOLIAN_DOC_TOKEN_MARK_TODO:
293 new_text += "<b>TODO: </b>";
294 break;
295 case ::EOLIAN_DOC_TOKEN_MARKUP_MONOSPACE:
296 new_text += "<c>" + token_text + "</c>";
297 break;
298 default:
299 break;
300 }
301 previous_token_type = token_type;
302 }
303 // Free this paragraph
304 free(par);
305 // Fetch the next paragraph
306 data = ::eina_list_next(data);
307 // If there's another paragraph afterwards, separate them with a blank line
308 if (data) new_text += "\n\n";
309 } while (data);
310 ::eina_list_free(paragraphs);
295 return new_text; 311 return new_text;
296 } 312 }
297 313
diff --git a/src/lib/eolian_cxx/grammar/klass_def.hpp b/src/lib/eolian_cxx/grammar/klass_def.hpp
index ad3b6ee..86fb61e 100644
--- a/src/lib/eolian_cxx/grammar/klass_def.hpp
+++ b/src/lib/eolian_cxx/grammar/klass_def.hpp
@@ -260,7 +260,8 @@ struct documentation_def
260 str = eolian_documentation_description_get(eolian_doc); 260 str = eolian_documentation_description_get(eolian_doc);
261 if (str) { 261 if (str) {
262 description = str; 262 description = str;
263 full_text += "\n" + description; 263 // Separate summary from description with a blank line
264 full_text += "\n\n" + description;
264 } 265 }
265 266
266 str = eolian_documentation_since_get(eolian_doc); 267 str = eolian_documentation_since_get(eolian_doc);