Skip to content

Commit 955d71d

Browse files
LightBenderLightBender
committed
Improve flag language. Fix margins.
1 parent 0a91cca commit 955d71d

6 files changed

Lines changed: 69 additions & 50 deletions

File tree

‎changelog/dmd.ddoc-behavior-flags.dd‎

Lines changed: 11 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,16 @@
11
Ddoc now emits behavior-flag badges for function guarantees
22

33
Documented functions now display badge-like $(I behavior flags) under their
4-
title, similar to the build-status badges seen in project READMEs. Four flags
5-
are available, each shown only when it applies and each in a distinct color:
4+
title, similar to the build-status badges seen in project READMEs. When any are
5+
present, the badges are introduced by a `Behaviors:` label. Four flags are
6+
available, each shown only when it applies and each in a distinct color:
67

78
$(UL
8-
$(LI `$(DOLLAR)(NOGC)` $(MDASH) emitted automatically for `@nogc` functions)
9-
$(LI `$(DOLLAR)(NOTHROW)` $(MDASH) emitted automatically for `nothrow` functions)
10-
$(LI `$(DOLLAR)(PURE)` $(MDASH) emitted automatically for `pure` functions)
11-
$(LI `$(DOLLAR)(NOALLOC)` $(MDASH) a manual-only "no-alloc" flag with no
12-
corresponding language attribute)
9+
$(LI `$(DOLLAR)(NOGC)` (rendered $(I No GC)) $(MDASH) emitted automatically for `@nogc` functions)
10+
$(LI `$(DOLLAR)(NOTHROW)` (rendered $(I No Exceptions Thrown)) $(MDASH) emitted automatically for `nothrow` functions)
11+
$(LI `$(DOLLAR)(PURE)` (rendered $(I Is Pure)) $(MDASH) emitted automatically for `pure` functions)
12+
$(LI `$(DOLLAR)(NOALLOC)` (rendered $(I No Allocations)) $(MDASH) a manual-only
13+
flag with no corresponding language attribute)
1314
)
1415

1516
The `$(DOLLAR)(NOGC)`, `$(DOLLAR)(NOTHROW)` and `$(DOLLAR)(PURE)` flags appear
@@ -28,8 +29,9 @@ $(DOLLAR)(NOALLOC)
2829
void* fastCopy(void* dst, const(void)* src, size_t n) @nogc nothrow pure;
2930
-------
3031

31-
The example above renders a `no-alloc` badge (written manually) next to the
32-
`@nogc`, `nothrow` and `pure` badges (added automatically from the attributes).
32+
The example above renders a $(I No Allocations) badge (written manually) next to
33+
the $(I No GC), $(I No Exceptions Thrown) and $(I Is Pure) badges (added
34+
automatically from the attributes), all shown after a `Behaviors:` label.
3335

3436
The badges and their grouping container are produced by the new `NOALLOC`,
3537
`NOGC`, `NOTHROW`, `PURE` and `DDOC_FLAGS` macros, which can be redefined like

‎compiler/src/dmd/res/default_ddoc_theme.ddoc‎

Lines changed: 13 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -65,11 +65,11 @@ YELLOW = <span class="color_yellow">$0</span>
6565
BLACK = <span class="color_black">$0</span>
6666
WHITE = <span class="color_white">$0</span>
6767

68-
NOALLOC = <span class="ddoc_flag ddoc_flag_noalloc" title="Does not allocate">no&#8209;alloc</span>
69-
NOGC = <span class="ddoc_flag ddoc_flag_nogc" title="Does not use the garbage collector">@nogc</span>
70-
NOTHROW = <span class="ddoc_flag ddoc_flag_nothrow" title="Does not throw exceptions">nothrow</span>
71-
PURE = <span class="ddoc_flag ddoc_flag_pure" title="Has no observable side effects">pure</span>
72-
DDOC_FLAGS = <div class="ddoc_flags">$0</div>$(LF)
68+
NOALLOC = <span class="ddoc_flag ddoc_flag_noalloc" title="Does not allocate">No Allocations</span>
69+
NOGC = <span class="ddoc_flag ddoc_flag_nogc" title="Does not use the garbage collector">No GC</span>
70+
NOTHROW = <span class="ddoc_flag ddoc_flag_nothrow" title="Does not throw exceptions">No Exceptions Thrown</span>
71+
PURE = <span class="ddoc_flag ddoc_flag_pure" title="Has no observable side effects">Is Pure</span>
72+
DDOC_FLAGS = <div class="ddoc_flags"><span class="ddoc_flags_label">Behaviors:</span>$0</div>$(LF)
7373

7474
D_CODE =
7575
<section class="code_listing">
@@ -174,7 +174,14 @@ DDOC =
174174
display: flex;
175175
flex-wrap: wrap;
176176
gap: 6px;
177-
margin: 6px 0 4px;
177+
margin: 0px 5px 5px 5px;
178+
}
179+
180+
.ddoc_flags_label {
181+
align-self: center;
182+
font-weight: bold;
183+
font-size: 11px;
184+
margin-right: 2px;
178185
}
179186

180187
.ddoc_flag {

‎compiler/test/compilable/extra-files/ddoc10.html‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -582,7 +582,7 @@ <h4>Declaration</h4>
582582
</section>
583583
</div>
584584
<div class="ddoc_decl">
585-
<div class="ddoc_flags"><span class="ddoc_flag ddoc_flag_nothrow" title="Does not throw exceptions">nothrow</span><span class="ddoc_flag ddoc_flag_pure" title="Has no observable side effects">pure</span></div>
585+
<div class="ddoc_flags"><span class="ddoc_flags_label">Behaviors:</span><span class="ddoc_flag ddoc_flag_nothrow" title="Does not throw exceptions">No Exceptions Thrown</span><span class="ddoc_flag ddoc_flag_pure" title="Has no observable side effects">Is Pure</span></div>
586586

587587

588588
</div>
@@ -608,7 +608,7 @@ <h4>Declaration</h4>
608608
</section>
609609
</div>
610610
<div class="ddoc_decl">
611-
<div class="ddoc_flags"><span class="ddoc_flag ddoc_flag_nothrow" title="Does not throw exceptions">nothrow</span><span class="ddoc_flag ddoc_flag_pure" title="Has no observable side effects">pure</span></div>
611+
<div class="ddoc_flags"><span class="ddoc_flags_label">Behaviors:</span><span class="ddoc_flag ddoc_flag_nothrow" title="Does not throw exceptions">No Exceptions Thrown</span><span class="ddoc_flag ddoc_flag_pure" title="Has no observable side effects">Is Pure</span></div>
612612

613613

614614
</div>

‎compiler/test/compilable/extra-files/ddoc14.html‎

Lines changed: 21 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -117,7 +117,7 @@ <h4>Declaration</h4>
117117
</section>
118118
</div>
119119
<div class="ddoc_decl">
120-
<div class="ddoc_flags"><span class="ddoc_flag ddoc_flag_nothrow" title="Does not throw exceptions">nothrow</span><span class="ddoc_flag ddoc_flag_pure" title="Has no observable side effects">pure</span></div>
120+
<div class="ddoc_flags"><span class="ddoc_flags_label">Behaviors:</span><span class="ddoc_flag ddoc_flag_nothrow" title="Does not throw exceptions">No Exceptions Thrown</span><span class="ddoc_flag ddoc_flag_pure" title="Has no observable side effects">Is Pure</span></div>
121121
<section class="section ddoc_sections">
122122
<div class="ddoc_summary">
123123
<p class="para">
@@ -150,7 +150,7 @@ <h4>Declaration</h4>
150150
</section>
151151
</div>
152152
<div class="ddoc_decl">
153-
<div class="ddoc_flags"><span class="ddoc_flag ddoc_flag_nothrow" title="Does not throw exceptions">nothrow</span><span class="ddoc_flag ddoc_flag_pure" title="Has no observable side effects">pure</span></div>
153+
<div class="ddoc_flags"><span class="ddoc_flags_label">Behaviors:</span><span class="ddoc_flag ddoc_flag_nothrow" title="Does not throw exceptions">No Exceptions Thrown</span><span class="ddoc_flag ddoc_flag_pure" title="Has no observable side effects">Is Pure</span></div>
154154
<section class="section ddoc_sections">
155155
<div class="ddoc_summary">
156156
<p class="para">
@@ -183,7 +183,7 @@ <h4>Declaration</h4>
183183
</section>
184184
</div>
185185
<div class="ddoc_decl">
186-
<div class="ddoc_flags"><span class="ddoc_flag ddoc_flag_nothrow" title="Does not throw exceptions">nothrow</span><span class="ddoc_flag ddoc_flag_pure" title="Has no observable side effects">pure</span></div>
186+
<div class="ddoc_flags"><span class="ddoc_flags_label">Behaviors:</span><span class="ddoc_flag ddoc_flag_nothrow" title="Does not throw exceptions">No Exceptions Thrown</span><span class="ddoc_flag ddoc_flag_pure" title="Has no observable side effects">Is Pure</span></div>
187187
<section class="section ddoc_sections">
188188
<div class="ddoc_summary">
189189
<p class="para">
@@ -216,7 +216,7 @@ <h4>Declaration</h4>
216216
</section>
217217
</div>
218218
<div class="ddoc_decl">
219-
<div class="ddoc_flags"><span class="ddoc_flag ddoc_flag_nothrow" title="Does not throw exceptions">nothrow</span><span class="ddoc_flag ddoc_flag_pure" title="Has no observable side effects">pure</span></div>
219+
<div class="ddoc_flags"><span class="ddoc_flags_label">Behaviors:</span><span class="ddoc_flag ddoc_flag_nothrow" title="Does not throw exceptions">No Exceptions Thrown</span><span class="ddoc_flag ddoc_flag_pure" title="Has no observable side effects">Is Pure</span></div>
220220
<section class="section ddoc_sections">
221221
<div class="ddoc_summary">
222222
<p class="para">
@@ -249,7 +249,7 @@ <h4>Declaration</h4>
249249
</section>
250250
</div>
251251
<div class="ddoc_decl">
252-
<div class="ddoc_flags"><span class="ddoc_flag ddoc_flag_nothrow" title="Does not throw exceptions">nothrow</span><span class="ddoc_flag ddoc_flag_pure" title="Has no observable side effects">pure</span></div>
252+
<div class="ddoc_flags"><span class="ddoc_flags_label">Behaviors:</span><span class="ddoc_flag ddoc_flag_nothrow" title="Does not throw exceptions">No Exceptions Thrown</span><span class="ddoc_flag ddoc_flag_pure" title="Has no observable side effects">Is Pure</span></div>
253253
<section class="section ddoc_sections">
254254
<div class="ddoc_summary">
255255
<p class="para">
@@ -282,7 +282,7 @@ <h4>Declaration</h4>
282282
</section>
283283
</div>
284284
<div class="ddoc_decl">
285-
<div class="ddoc_flags"><span class="ddoc_flag ddoc_flag_nothrow" title="Does not throw exceptions">nothrow</span><span class="ddoc_flag ddoc_flag_pure" title="Has no observable side effects">pure</span></div>
285+
<div class="ddoc_flags"><span class="ddoc_flags_label">Behaviors:</span><span class="ddoc_flag ddoc_flag_nothrow" title="Does not throw exceptions">No Exceptions Thrown</span><span class="ddoc_flag ddoc_flag_pure" title="Has no observable side effects">Is Pure</span></div>
286286
<section class="section ddoc_sections">
287287
<div class="ddoc_summary">
288288
<p class="para">
@@ -315,7 +315,7 @@ <h4>Declaration</h4>
315315
</section>
316316
</div>
317317
<div class="ddoc_decl">
318-
<div class="ddoc_flags"><span class="ddoc_flag ddoc_flag_nothrow" title="Does not throw exceptions">nothrow</span><span class="ddoc_flag ddoc_flag_pure" title="Has no observable side effects">pure</span></div>
318+
<div class="ddoc_flags"><span class="ddoc_flags_label">Behaviors:</span><span class="ddoc_flag ddoc_flag_nothrow" title="Does not throw exceptions">No Exceptions Thrown</span><span class="ddoc_flag ddoc_flag_pure" title="Has no observable side effects">Is Pure</span></div>
319319
<section class="section ddoc_sections">
320320
<div class="ddoc_summary">
321321
<p class="para">
@@ -447,7 +447,7 @@ <h4>Declaration</h4>
447447
</section>
448448
</div>
449449
<div class="ddoc_decl">
450-
<div class="ddoc_flags"><span class="ddoc_flag ddoc_flag_nothrow" title="Does not throw exceptions">nothrow</span><span class="ddoc_flag ddoc_flag_pure" title="Has no observable side effects">pure</span></div>
450+
<div class="ddoc_flags"><span class="ddoc_flags_label">Behaviors:</span><span class="ddoc_flag ddoc_flag_nothrow" title="Does not throw exceptions">No Exceptions Thrown</span><span class="ddoc_flag ddoc_flag_pure" title="Has no observable side effects">Is Pure</span></div>
451451
<section class="section ddoc_sections">
452452
<div class="ddoc_summary">
453453
<p class="para">
@@ -480,7 +480,7 @@ <h4>Declaration</h4>
480480
</section>
481481
</div>
482482
<div class="ddoc_decl">
483-
<div class="ddoc_flags"><span class="ddoc_flag ddoc_flag_nothrow" title="Does not throw exceptions">nothrow</span><span class="ddoc_flag ddoc_flag_pure" title="Has no observable side effects">pure</span></div>
483+
<div class="ddoc_flags"><span class="ddoc_flags_label">Behaviors:</span><span class="ddoc_flag ddoc_flag_nothrow" title="Does not throw exceptions">No Exceptions Thrown</span><span class="ddoc_flag ddoc_flag_pure" title="Has no observable side effects">Is Pure</span></div>
484484
<section class="section ddoc_sections">
485485
<div class="ddoc_summary">
486486
<p class="para">
@@ -513,7 +513,7 @@ <h4>Declaration</h4>
513513
</section>
514514
</div>
515515
<div class="ddoc_decl">
516-
<div class="ddoc_flags"><span class="ddoc_flag ddoc_flag_nothrow" title="Does not throw exceptions">nothrow</span><span class="ddoc_flag ddoc_flag_pure" title="Has no observable side effects">pure</span></div>
516+
<div class="ddoc_flags"><span class="ddoc_flags_label">Behaviors:</span><span class="ddoc_flag ddoc_flag_nothrow" title="Does not throw exceptions">No Exceptions Thrown</span><span class="ddoc_flag ddoc_flag_pure" title="Has no observable side effects">Is Pure</span></div>
517517
<section class="section ddoc_sections">
518518
<div class="ddoc_summary">
519519
<p class="para">
@@ -546,7 +546,7 @@ <h4>Declaration</h4>
546546
</section>
547547
</div>
548548
<div class="ddoc_decl">
549-
<div class="ddoc_flags"><span class="ddoc_flag ddoc_flag_nothrow" title="Does not throw exceptions">nothrow</span><span class="ddoc_flag ddoc_flag_pure" title="Has no observable side effects">pure</span></div>
549+
<div class="ddoc_flags"><span class="ddoc_flags_label">Behaviors:</span><span class="ddoc_flag ddoc_flag_nothrow" title="Does not throw exceptions">No Exceptions Thrown</span><span class="ddoc_flag ddoc_flag_pure" title="Has no observable side effects">Is Pure</span></div>
550550
<section class="section ddoc_sections">
551551
<div class="ddoc_summary">
552552
<p class="para">
@@ -579,7 +579,7 @@ <h4>Declaration</h4>
579579
</section>
580580
</div>
581581
<div class="ddoc_decl">
582-
<div class="ddoc_flags"><span class="ddoc_flag ddoc_flag_nothrow" title="Does not throw exceptions">nothrow</span><span class="ddoc_flag ddoc_flag_pure" title="Has no observable side effects">pure</span></div>
582+
<div class="ddoc_flags"><span class="ddoc_flags_label">Behaviors:</span><span class="ddoc_flag ddoc_flag_nothrow" title="Does not throw exceptions">No Exceptions Thrown</span><span class="ddoc_flag ddoc_flag_pure" title="Has no observable side effects">Is Pure</span></div>
583583
<section class="section ddoc_sections">
584584
<div class="ddoc_summary">
585585
<p class="para">
@@ -612,7 +612,7 @@ <h4>Declaration</h4>
612612
</section>
613613
</div>
614614
<div class="ddoc_decl">
615-
<div class="ddoc_flags"><span class="ddoc_flag ddoc_flag_nothrow" title="Does not throw exceptions">nothrow</span><span class="ddoc_flag ddoc_flag_pure" title="Has no observable side effects">pure</span></div>
615+
<div class="ddoc_flags"><span class="ddoc_flags_label">Behaviors:</span><span class="ddoc_flag ddoc_flag_nothrow" title="Does not throw exceptions">No Exceptions Thrown</span><span class="ddoc_flag ddoc_flag_pure" title="Has no observable side effects">Is Pure</span></div>
616616
<section class="section ddoc_sections">
617617
<div class="ddoc_summary">
618618
<p class="para">
@@ -645,7 +645,7 @@ <h4>Declaration</h4>
645645
</section>
646646
</div>
647647
<div class="ddoc_decl">
648-
<div class="ddoc_flags"><span class="ddoc_flag ddoc_flag_nothrow" title="Does not throw exceptions">nothrow</span><span class="ddoc_flag ddoc_flag_pure" title="Has no observable side effects">pure</span></div>
648+
<div class="ddoc_flags"><span class="ddoc_flags_label">Behaviors:</span><span class="ddoc_flag ddoc_flag_nothrow" title="Does not throw exceptions">No Exceptions Thrown</span><span class="ddoc_flag ddoc_flag_pure" title="Has no observable side effects">Is Pure</span></div>
649649
<section class="section ddoc_sections">
650650
<div class="ddoc_summary">
651651
<p class="para">
@@ -747,7 +747,7 @@ <h4>Declaration</h4>
747747
</section>
748748
</div>
749749
<div class="ddoc_decl">
750-
<div class="ddoc_flags"><span class="ddoc_flag ddoc_flag_nothrow" title="Does not throw exceptions">nothrow</span><span class="ddoc_flag ddoc_flag_pure" title="Has no observable side effects">pure</span></div>
750+
<div class="ddoc_flags"><span class="ddoc_flags_label">Behaviors:</span><span class="ddoc_flag ddoc_flag_nothrow" title="Does not throw exceptions">No Exceptions Thrown</span><span class="ddoc_flag ddoc_flag_pure" title="Has no observable side effects">Is Pure</span></div>
751751
<section class="section ddoc_sections">
752752
<div class="ddoc_summary">
753753
<p class="para">
@@ -780,7 +780,7 @@ <h4>Declaration</h4>
780780
</section>
781781
</div>
782782
<div class="ddoc_decl">
783-
<div class="ddoc_flags"><span class="ddoc_flag ddoc_flag_nothrow" title="Does not throw exceptions">nothrow</span><span class="ddoc_flag ddoc_flag_pure" title="Has no observable side effects">pure</span></div>
783+
<div class="ddoc_flags"><span class="ddoc_flags_label">Behaviors:</span><span class="ddoc_flag ddoc_flag_nothrow" title="Does not throw exceptions">No Exceptions Thrown</span><span class="ddoc_flag ddoc_flag_pure" title="Has no observable side effects">Is Pure</span></div>
784784
<section class="section ddoc_sections">
785785
<div class="ddoc_summary">
786786
<p class="para">
@@ -813,7 +813,7 @@ <h4>Declaration</h4>
813813
</section>
814814
</div>
815815
<div class="ddoc_decl">
816-
<div class="ddoc_flags"><span class="ddoc_flag ddoc_flag_nothrow" title="Does not throw exceptions">nothrow</span><span class="ddoc_flag ddoc_flag_pure" title="Has no observable side effects">pure</span></div>
816+
<div class="ddoc_flags"><span class="ddoc_flags_label">Behaviors:</span><span class="ddoc_flag ddoc_flag_nothrow" title="Does not throw exceptions">No Exceptions Thrown</span><span class="ddoc_flag ddoc_flag_pure" title="Has no observable side effects">Is Pure</span></div>
817817
<section class="section ddoc_sections">
818818
<div class="ddoc_summary">
819819
<p class="para">
@@ -846,7 +846,7 @@ <h4>Declaration</h4>
846846
</section>
847847
</div>
848848
<div class="ddoc_decl">
849-
<div class="ddoc_flags"><span class="ddoc_flag ddoc_flag_nothrow" title="Does not throw exceptions">nothrow</span><span class="ddoc_flag ddoc_flag_pure" title="Has no observable side effects">pure</span></div>
849+
<div class="ddoc_flags"><span class="ddoc_flags_label">Behaviors:</span><span class="ddoc_flag ddoc_flag_nothrow" title="Does not throw exceptions">No Exceptions Thrown</span><span class="ddoc_flag ddoc_flag_pure" title="Has no observable side effects">Is Pure</span></div>
850850
<section class="section ddoc_sections">
851851
<div class="ddoc_summary">
852852
<p class="para">
@@ -879,7 +879,7 @@ <h4>Declaration</h4>
879879
</section>
880880
</div>
881881
<div class="ddoc_decl">
882-
<div class="ddoc_flags"><span class="ddoc_flag ddoc_flag_nothrow" title="Does not throw exceptions">nothrow</span><span class="ddoc_flag ddoc_flag_pure" title="Has no observable side effects">pure</span></div>
882+
<div class="ddoc_flags"><span class="ddoc_flags_label">Behaviors:</span><span class="ddoc_flag ddoc_flag_nothrow" title="Does not throw exceptions">No Exceptions Thrown</span><span class="ddoc_flag ddoc_flag_pure" title="Has no observable side effects">Is Pure</span></div>
883883
<section class="section ddoc_sections">
884884
<div class="ddoc_summary">
885885
<p class="para">
@@ -912,7 +912,7 @@ <h4>Declaration</h4>
912912
</section>
913913
</div>
914914
<div class="ddoc_decl">
915-
<div class="ddoc_flags"><span class="ddoc_flag ddoc_flag_nothrow" title="Does not throw exceptions">nothrow</span><span class="ddoc_flag ddoc_flag_pure" title="Has no observable side effects">pure</span></div>
915+
<div class="ddoc_flags"><span class="ddoc_flags_label">Behaviors:</span><span class="ddoc_flag ddoc_flag_nothrow" title="Does not throw exceptions">No Exceptions Thrown</span><span class="ddoc_flag ddoc_flag_pure" title="Has no observable side effects">Is Pure</span></div>
916916
<section class="section ddoc_sections">
917917
<div class="ddoc_summary">
918918
<p class="para">
@@ -945,7 +945,7 @@ <h4>Declaration</h4>
945945
</section>
946946
</div>
947947
<div class="ddoc_decl">
948-
<div class="ddoc_flags"><span class="ddoc_flag ddoc_flag_nothrow" title="Does not throw exceptions">nothrow</span><span class="ddoc_flag ddoc_flag_pure" title="Has no observable side effects">pure</span></div>
948+
<div class="ddoc_flags"><span class="ddoc_flags_label">Behaviors:</span><span class="ddoc_flag ddoc_flag_nothrow" title="Does not throw exceptions">No Exceptions Thrown</span><span class="ddoc_flag ddoc_flag_pure" title="Has no observable side effects">Is Pure</span></div>
949949
<section class="section ddoc_sections">
950950
<div class="ddoc_summary">
951951
<p class="para">

‎compiler/test/compilable/extra-files/ddocYear.html‎

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -68,7 +68,14 @@
6868
display: flex;
6969
flex-wrap: wrap;
7070
gap: 6px;
71-
margin: 6px 0 4px;
71+
margin: 0px 5px 5px 5px;
72+
}
73+
74+
.ddoc_flags_label {
75+
align-self: center;
76+
font-weight: bold;
77+
font-size: 11px;
78+
margin-right: 2px;
7279
}
7380

7481
.ddoc_flag {

0 commit comments

Comments
 (0)