summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorXavi Artigas <xavierartigas@yahoo.es>2019-07-23 16:38:04 +0200
committerXavi Artigas <xavierartigas@yahoo.es>2019-07-23 21:53:01 +0200
commit5585420e858bbb17ae3b7cc599b4a0f2eb178075 (patch)
treef91520fc738e36a13919709d777bb9e267f8e529
parent3eb7b3793b0afcc79143a74a4052cb6179334f08 (diff)
mono-docs: Indicate when a class is BETA
Summary: The mono generator adds a <remarks> section to all BETA classes with an explanatory text. These tags are understood by DocFX and Monodevelop. On top of this, this commit modifies the DocFX template to give the Remarks section a more prominent place in the page. Test Plan: Render docs, Beta classes should have a big blue box with a remark about the class being Beta and dangerous. Reviewers: lauromoura, vitor.sousa Subscribers: cedric, #reviewers, #committers Tags: #efl Differential Revision: https://phab.enlightenment.org/D9381
-rw-r--r--doc/docfx/default_efl/partials/class.header.tmpl.partial10
-rw-r--r--doc/docfx/default_efl/partials/class.tmpl.partial4
-rw-r--r--doc/docfx/default_efl/styles/docfx.css6
-rw-r--r--src/bin/eolian_mono/eolian/mono/documentation.hh6
4 files changed, 18 insertions, 8 deletions
diff --git a/doc/docfx/default_efl/partials/class.header.tmpl.partial b/doc/docfx/default_efl/partials/class.header.tmpl.partial
index f6bff1af39..18c6dc7341 100644
--- a/doc/docfx/default_efl/partials/class.header.tmpl.partial
+++ b/doc/docfx/default_efl/partials/class.header.tmpl.partial
@@ -3,6 +3,12 @@
3<h1 id="{{id}}" data-uid="{{uid}}" class="text-break">{{>partials/title}}</h1> 3<h1 id="{{id}}" data-uid="{{uid}}" class="text-break">{{>partials/title}}</h1>
4<div class="markdown level0 summary">{{{summary}}}</div> 4<div class="markdown level0 summary">{{{summary}}}</div>
5<div class="markdown level0 conceptual">{{{conceptual}}}</div> 5<div class="markdown level0 conceptual">{{{conceptual}}}</div>
6{{#remarks}}
7<div class="remarks">
8<h5 id="{{id}}_remarks"><strong>{{__global.remarks}}</strong></h5>
9{{{remarks}}}
10</div>
11{{/remarks}}
6{{#inClass}} 12{{#inClass}}
7<div class="inheritance"> 13<div class="inheritance">
8 <h5>{{__global.inheritance}}</h5> 14 <h5>{{__global.inheritance}}</h5>
@@ -82,10 +88,6 @@
82 </tbody> 88 </tbody>
83</table> 89</table>
84{{/syntax.typeParameters.0}} 90{{/syntax.typeParameters.0}}
85{{#remarks}}
86<h5 id="{{id}}_remarks"><strong>{{__global.remarks}}</strong></h5>
87<div class="markdown level0 remarks">{{{remarks}}}</div>
88{{/remarks}}
89{{#example.0}} 91{{#example.0}}
90<h5 id="{{id}}_examples"><strong>{{__global.examples}}</strong></h5> 92<h5 id="{{id}}_examples"><strong>{{__global.examples}}</strong></h5>
91{{/example.0}} 93{{/example.0}}
diff --git a/doc/docfx/default_efl/partials/class.tmpl.partial b/doc/docfx/default_efl/partials/class.tmpl.partial
index ae9de66364..75bfce0e9b 100644
--- a/doc/docfx/default_efl/partials/class.tmpl.partial
+++ b/doc/docfx/default_efl/partials/class.tmpl.partial
@@ -143,10 +143,6 @@
143<h5 class="overrides">{{__global.overrides}}</h5> 143<h5 class="overrides">{{__global.overrides}}</h5>
144<div><xref uid="{{uid}}" altProperty="fullName" displayProperty="nameWithType"/></div> 144<div><xref uid="{{uid}}" altProperty="fullName" displayProperty="nameWithType"/></div>
145{{/overridden}} 145{{/overridden}}
146{{#remarks}}
147<h5 id="{{id}}_remarks">{{__global.remarks}}</h5>
148<div class="markdown level1 remarks">{{{remarks}}}</div>
149{{/remarks}}
150{{#example.0}} 146{{#example.0}}
151<h5 id="{{id}}_examples">{{__global.examples}}</h5> 147<h5 id="{{id}}_examples">{{__global.examples}}</h5>
152{{/example.0}} 148{{/example.0}}
diff --git a/doc/docfx/default_efl/styles/docfx.css b/doc/docfx/default_efl/styles/docfx.css
index f94c4b0377..81beac718e 100644
--- a/doc/docfx/default_efl/styles/docfx.css
+++ b/doc/docfx/default_efl/styles/docfx.css
@@ -995,3 +995,9 @@ div.embeddedvideo iframe {
995 995
996.mainContainer[dir='rtl'] main ul[role="tablist"] { 996.mainContainer[dir='rtl'] main ul[role="tablist"] {
997 margin: 0; } 997 margin: 0; }
998
999.remarks {
1000 background-color: #c0c0ff;
1001 border-radius: 6px;
1002 padding: 6px;
1003}
diff --git a/src/bin/eolian_mono/eolian/mono/documentation.hh b/src/bin/eolian_mono/eolian/mono/documentation.hh
index a672d209b4..26e5645eb2 100644
--- a/src/bin/eolian_mono/eolian/mono/documentation.hh
+++ b/src/bin/eolian_mono/eolian/mono/documentation.hh
@@ -12,6 +12,7 @@
12#include <Eina.h> 12#include <Eina.h>
13 13
14static const std::string BETA_REF_SUFFIX = " (object still in beta stage)"; 14static const std::string BETA_REF_SUFFIX = " (object still in beta stage)";
15static const std::string BETA_SUMMARY_REMARKS = "This is a \\<b\\>BETA\\</b\\> class. It can be modified or removed in the future. Do not use it for product development.";
15 16
16namespace eolian_mono { 17namespace eolian_mono {
17 18
@@ -390,6 +391,11 @@ struct documentation_generator
390 { 391 {
391 if (!generate(sink, klass.documentation, context)) return false; 392 if (!generate(sink, klass.documentation, context)) return false;
392 393
394 if (klass.is_beta)
395 {
396 if (!generate_tag(sink, "remarks", BETA_SUMMARY_REMARKS, context)) return false;
397 }
398
393 std::string klass_name = name_helpers::klass_full_concrete_or_interface_name(klass); 399 std::string klass_name = name_helpers::klass_full_concrete_or_interface_name(klass);
394 return generate_tag_example(sink, klass_name, context); 400 return generate_tag_example(sink, klass_name, context);
395 } 401 }