summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorJoão Paulo Taylor Ienczak Zanette <joao.tiz@expertisesolutions.com.br>2020-01-20 18:42:05 +0000
committerFelipe Magno de Almeida <felipe@expertisesolutions.com.br>2020-02-13 15:38:42 -0300
commit651517808cfd7ec2743b23ccc17d1473abc61393 (patch)
tree72dadcfd1ea434a50f93de2274636f4478e3ea5d
parent4f3b3a33f5b8b93cfbfb0740318087d277639ea4 (diff)
csharp: Generating documentation for tuple-value properties.
Adds documentation for tuple-value properties (properties with multiple values), so the following Eo: ``` @property multi_valued_prop { [[ A multi valued property. ]] get {} set {} values { prop1: int; [[ Dummy property's first element. ]] prop2: int; [[ Dummy property's second element. ]] } } ``` Generates the following documentation: ``` /// <summary>A multi valued property.<br/> /// Since EFL *current version*.</summary> /// <value>A tuple containing the following information: /// <list type="bullet"> /// <item><description><c>prop1</c> (<c>Item0</c>): Dummy property&apos;s first element.</description></item> /// <item><description><c>prop2</c> (<c>Item1</c>): Dummy property&apos;s second element.</description></item> /// </list></value> ``` Note: This commit also adds a default separator between tag name and parameters in `generate_opening_tag`. Ref T8468. Differential Revision: https://phab.enlightenment.org/D10889
-rw-r--r--src/bin/eolian_mono/eolian/mono/documentation.hh94
-rw-r--r--src/tests/efl_mono/dummy_test_object.eo5
2 files changed, 94 insertions, 5 deletions
diff --git a/src/bin/eolian_mono/eolian/mono/documentation.hh b/src/bin/eolian_mono/eolian/mono/documentation.hh
index d009e45..d15f914 100644
--- a/src/bin/eolian_mono/eolian/mono/documentation.hh
+++ b/src/bin/eolian_mono/eolian/mono/documentation.hh
@@ -315,7 +315,9 @@ struct documentation_generator
315 template<typename OutputIterator, typename Context> 315 template<typename OutputIterator, typename Context>
316 bool generate_opening_tag(OutputIterator sink, std::string const& tag, Context const& context, std::string tag_params = "") const 316 bool generate_opening_tag(OutputIterator sink, std::string const& tag, Context const& context, std::string tag_params = "") const
317 { 317 {
318 return as_generator("<" << tag << tag_params << ">").generate(sink, attributes::unused, context); 318 auto tag_separator = tag_params.empty() ? "" : " ";
319
320 return as_generator("<" << tag << tag_separator << tag_params << ">").generate(sink, attributes::unused, context);
319 } 321 }
320 322
321 template<typename OutputIterator, typename Context> 323 template<typename OutputIterator, typename Context>
@@ -461,6 +463,69 @@ struct documentation_generator
461 return generate_tag_example(sink, klass_name, context); 463 return generate_tag_example(sink, klass_name, context);
462 } 464 }
463 465
466 /*! Generates documentation for tuple-value properties.
467 *
468 * Example:
469 *
470 * A tuple containing the following information:
471 * <list type="bullet">
472 * <item><description><c>a</c>: Parameter a.</description></item>
473 * <item><description><c>b</c>: Parameter b.</description></item>
474 * </list>
475 *
476 * \param index_names If true, tuple items are referenced by their index. If
477 * false, they are referenced by their names instead.
478 */
479 template<typename OutputIterator, typename Context>
480 bool generate_tuple_parameters_doc(OutputIterator sink,
481 std::vector<attributes::parameter_def> const& parameters,
482 Context const& context,
483 bool numbered_refs = false) const
484 {
485 if (!(as_generator(scope_tab(scope_size) << "/// ")
486 .generate(sink, attributes::unused, context)
487 && as_generator(
488 "A tuple containing the following information:\n"
489 << scope_tab(scope_size) << "/// "
490 ).generate(sink, attributes::unused, context)
491 && generate_opening_tag(sink, "list", context, "type=\"bullet\"")
492 && as_generator("\n" << scope_tab(scope_size) << "/// ")
493 .generate(sink, attributes::unused, context)))
494 return false;
495
496 auto i = 0u;
497 for (auto const& param: parameters)
498 {
499 auto name = param.param_name;
500 if (!(generate_opening_tag(sink, "item", context)
501 && generate_opening_tag(sink, "description", context)
502 && generate_opening_tag(sink, "c", context)
503 && as_generator(name).generate(sink, attributes::unused, context)
504 && generate_closing_tag(sink, "c", context)))
505 return false;
506
507 if (numbered_refs && !(
508 as_generator(" (").generate(sink, attributes::unused, context)
509 && generate_opening_tag(sink, "c", context)
510 && as_generator("Item" + std::to_string(i)).generate(sink, attributes::unused, context)
511 && generate_closing_tag(sink, "c", context)
512 && as_generator(")").generate(sink, attributes::unused, context)))
513 return false;
514
515 if (!(generate_escaped_content(sink, ": " + param.documentation.full_text, context)
516 && generate_closing_tag(sink, "description", context)
517 && generate_closing_tag(sink, "item", context)
518 && as_generator("\n" << scope_tab(scope_size) << "/// ")
519 .generate(sink, attributes::unused, context)))
520 return false;
521 ++i;
522 }
523
524 return generate_closing_tag(sink, "list", context)
525 && as_generator("\n")
526 .generate(sink, attributes::unused, context);
527 }
528
464 template<typename OutputIterator, typename Context> 529 template<typename OutputIterator, typename Context>
465 bool generate(OutputIterator sink, attributes::property_def const& prop, Context const& context) const 530 bool generate(OutputIterator sink, attributes::property_def const& prop, Context const& context) const
466 { 531 {
@@ -483,12 +548,35 @@ struct documentation_generator
483 548
484 text = ""; 549 text = "";
485 if (prop.setter.is_engaged()) 550 if (prop.setter.is_engaged())
486 text = prop.setter->parameters[0].documentation.full_text; 551 {
552 if (prop.setter.is_engaged() && prop.setter->values.size() > 1u)
553 {
554 if (!(
555 as_generator(scope_tab(scope_size) << "/// ")
556 .generate(sink, attributes::unused, context)
557 && generate_opening_tag(sink, "value", context)
558 && as_generator("\n")
559 .generate(sink, attributes::unused, context)
560 && generate_tuple_parameters_doc(sink, prop.setter->parameters, context, true)
561 && as_generator(scope_tab(scope_size) << "/// ")
562 .generate(sink, attributes::unused, context)
563 && generate_closing_tag(sink, "value", context)
564 && as_generator("\n")
565 .generate(sink, attributes::unused, context)
566 ))
567 return false;
568 }
569 else
570 text = prop.setter->parameters[0].documentation.full_text;
571 }
487 else if (prop.getter.is_engaged()) 572 else if (prop.getter.is_engaged())
488 text = prop.getter->return_documentation.full_text; 573 text = prop.getter->return_documentation.full_text;
489 // If there are no docs at all, do not generate <value> tag 574 // If there are no docs at all, do not generate <value> tag
490 if (!text.empty()) 575 if (!text.empty())
491 if (!generate_tag_value(sink, text, context)) return false; 576 if (!generate_tag_value(
577 sink,
578 text,
579 context)) return false;
492 580
493 return generate_all_tag_examples(sink, 581 return generate_all_tag_examples(sink,
494 name_helpers::klass_full_concrete_or_interface_name(prop.klass), 582 name_helpers::klass_full_concrete_or_interface_name(prop.klass),
diff --git a/src/tests/efl_mono/dummy_test_object.eo b/src/tests/efl_mono/dummy_test_object.eo
index a0199cb..39cc258 100644
--- a/src/tests/efl_mono/dummy_test_object.eo
+++ b/src/tests/efl_mono/dummy_test_object.eo
@@ -1576,11 +1576,12 @@ class Dummy.Test_Object extends Efl.Object implements Dummy.Test_Iface {
1576 } 1576 }
1577 1577
1578 @property multi_valued_prop { 1578 @property multi_valued_prop {
1579 [[ A multi valued property. ]]
1579 get {} 1580 get {}
1580 set {} 1581 set {}
1581 values { 1582 values {
1582 prop1: int; 1583 prop1: int; [[ Dummy property's first element. ]]
1583 prop2: int; 1584 prop2: int; [[ Dummy property's second element. ]]
1584 } 1585 }
1585 } 1586 }
1586 1587