1 // just docs: adrdox syntax 2 /++ 3 This document describes the syntax recognized by my documentation generator. It uses a hybrid of ddoc and markdown syntax, with some customizations and pre-defined styles I like, while not supporting things I feel aren't worth the hassle. 4 5 It has support for enough legacy ddoc that Phobos still works, but is really a different language - I think ddoc made a lot of mistakes (and markdown made mistakes too). 6 7 $(ADRDOX_SAMPLE 8 Paragraphs just work. 9 10 Automatically. 11 12 $(LIST 13 * Lists can be displayed 14 * in bracketed markdown style 15 ) 16 17 $(SMALL_TABLE 18 markdown | style 19 tables | work (if bracketed) 20 ) 21 22 --- 23 void d_code() { 24 is formatted brilliantly; 25 } 26 --- 27 28 ``` 29 Markdown-style code blocks work too for other languages 30 or convenient <pre> blocks. 31 ``` 32 33 ```java 34 public static void Main() { 35 return "With some syntax highlighting." 36 } 37 ``` 38 39 We also have `inline code`. 40 41 $(TIP and various content boxes.) 42 43 $(MATH \int \text{LaTeX} too! dx) 44 ) 45 46 47 $(H2 Document outline) 48 49 Your comment consists of three parts: the first paragraph, which is meant to be a stand-alone summary which is shown out-of-context in search results, the synopsis, which is displayed "above the fold" - before the function prototype, member list, or automatically generated table of contents, and finally, the rest of the documentation. 50 51 The fold is inserted at the first "\n\n\n" it finds in your comment (the first time it sees two blank lines: 52 53 $(ADRDOX_SAMPLE 54 55 This is the summary. It is shown in search results and 56 at the top of your generated document. 57 58 This is the synopsis, still displayed above the fold. 59 60 So is this. 61 62 63 The two blank lines above is the placeholder where the 64 table of contents is inserted. This paragraph, and 65 everything below it, is the bulk body of the page. 66 67 Line breaks in the middle of a paragraph, except in code 68 blocks, are ignored. You can format your comments however you like. 69 ) 70 71 $(H3 Symbol grouping) 72 73 You can optionally group symbols together by defining groups in a special section in your module definition comment, then tagging the doc comments on the items. 74 75 --- 76 /++ 77 This demos symbol grouping. 78 79 Symbol_groups: 80 81 group_name = 82 Introductory and explanatory text for the group. It may 83 include any kind of 84 85 drawing = 86 ## Drawing 87 88 This library supports several drawing functions. You 89 draw them all on a "surface" of sorts, derived from 90 [Drawable]. 91 +/ 92 module test; 93 94 /++ Group: group_name 95 Introductory text 96 97 and paragraphs like normal. 98 99 100 This goes below the fold. 101 +/ 102 void foo() {} 103 104 /++ 105 This is in the [drawing] group. 106 107 Group: drawing 108 +/ 109 interface Drawable { 110 /// Group: group_name 111 void whatever() {} 112 } 113 --- 114 115 The `Symbol_groups:` section should only appear on the module commment. The `Group: name` line MUST be the first thing to appear in a comment, or be on the very last line of the comment. It can only appear once. Putting a function in multiple groups is not current supported. 116 117 If there is no header at the start of the group definition, one will be automatically inserted based on the group name. 118 119 For cross referencing purposes, the groups are considered pseudo-symbols at module scope. This means you can refer to them with the shortcut `[symbol]` syntax from anywhere in the module, or from outside the module if used with a fully-qualified name. 120 121 However, for best results, it should not conflict with any real names in the module, nor with any [#footnotes|link references], which also introduce pseudo-symbols. If there is a conflict, the reference result is currently undefined (it may be any one of them, in no particular order). I will define that precedence order at some other time - so for now, avoid name conflicts! 122 123 $(H2 Macros) 124 125 adrdox inherits ddoc's macro syntax, but uses it differently than ddoc: it does not support user-defined macros, and sometimes uses them to bracket special syntax. 126 127 Any time you see me show ddoc macro syntax, `$(NAME )`, be aware that you can also use `${NAME }`. For example, if you have unbalanced parenthesis inside the thing, you may prefer to use `${}`. 128 129 ${ADRDOX_SAMPLE 130 $(B this is bold) 131 ${B so is this} 132 ${I this has unbalanced paren :) } 133 } 134 135 $(H2 Code snippets) 136 137 $(H3 Inline code) 138 139 Inline code can be marked with Markdown (and Ddoc) style ``code here ``, which will render as `code here`. Text inside the backticks suppress all other documentation generator processing - it will just be escaped for literal output. 140 141 $(TIP If you need to display a literal ``, use the `$(BACKTICK)` macro or a doubled backtick: ````.) 142 143 Code inside backticks may only span one line. If a line has an unmatched backtick, it is not processed as code. 144 145 If you want syntax-highlighted inline D code, use `$(D d code here)`, such as `$(D if(a is true))` will result in $(D if(a is true)) - notice the syntax highlighting on the D keywords. 146 147 $(H3 Block code) 148 149 There are three syntaxes for code blocks: Markdown style $(BACKTICK)$(BACKTICK)$(BACKTICK), ddoc style ---, and a magic macro called `$(CONSOLE)`. 150 151 All code blocks are outdented and leading and trailing blank lines are removed, but all other whitespace is left intact. This means you may indent it as much as you like inside your comments without breaking the output. 152 153 $(H4 Markdown style - for generic code) 154 155 The Markdown style block is meant to be used with generic code or preformatted text that is not D. 156 157 $(ADRDOX_SAMPLE 158 ``` 159 Code here which preserves 160 whitespace 161 ``` 162 ) 163 164 You can optionally include a language name after the opening ticks and it will label and attempt syntax highlighting (the syntax highlighter is not as precise as the D highlighter, but often should be good enough): 165 166 $(ADRDOX_SAMPLE 167 ```javascript 168 /* This is highlighted Javascript! */ 169 window.onload = function() { 170 var a = "hello, world!"; 171 var b = 5; 172 }; 173 ``` 174 175 ```c 176 /* Highlighted C */ 177 #include<stdio.h> 178 typedef struct { 179 int a; 180 } test; 181 ``` 182 183 ```php 184 <?php 185 # highlighted PHP 186 function foo($a) { 187 $a = 'hello'; 188 return $a; 189 } 190 ?> 191 ``` 192 193 ```python 194 # highlighted python 195 class test: 196 """ docstring """ 197 def myfunc(): 198 if True or 1 > 0: 199 print "hello" 200 else 201 print test 202 ``` 203 204 ```html 205 <span class="foo"> 206 <!-- try hovering over the entity! --> 207 HTML & 208 </span> 209 ``` 210 211 ```css 212 /* This also highlights */ 213 span[data-test="foo"] > .bar { 214 color: red; 215 } 216 ``` 217 ) 218 219 Currently supported languages for highlighting include: C, C++, Javascript, PHP, Java, C#, CSS, HTML, XML, Python, Ruby, [arsd.script|adrscript] and D. Though, for D, you should use ddoc style `---` delimiters to get the full-featured D highlighter instead of using the simpler one here. This simple highlighter aims for good enough to help visually on simple examples rather than being perfect on each target language. 220 221 Use the language name in all lower case when tagging the language, like `php` or `c++`. 222 223 $(TIP If you ever want to document the syntax of a Markdown code block itself, I added a magic $(BACKTICK)$(BACKTICK)$(BACKTICK){ code }$(BACKTICK)$(BACKTICK)$(BACKTICK) syntax. As long as the braces are nested, everything inside will be considered part of the literal code block, including other code blocks.) 224 225 The generator MAY syntax highlight the language using `span` with class names, but might not (really depends on if I implement it). You may use the language as a target in CSS using the `data-language` attribute to customize the appearance. 226 227 $(H4 Ddoc style - for D code) 228 229 The ddoc style block only works with D code. It runs the sample through the D lexer, so it understands things like nested documentation comments and will properly skip them while syntax highlighting the output. 230 231 $(ADRDOX_SAMPLE 232 --- 233 /** 234 Ddoc style code blocks understand D deeply. 235 236 --- 237 if(example.nested) 238 stillWorks!(); 239 --- 240 */ 241 void main() {} 242 --- 243 ) 244 245 Ddoc style code samples are special in one way: you can highlight code inside it by using `/* adrdox_highlight{ */ code here would be highlighted /* }adrdox_highlight */` comments in the sample. Note that it matches those strings $(I exactly), meaning you must use `/* */` comments and must have the same spacing. `/* adrdox_highlight{ */` turns it on, `/* }adrdox_highlight */` turns it off. Note that if you don't turn it off, you may cause invalid html to be generated (the implementation just opens and closes a `span` element right now). 246 247 $(ADRDOX_SAMPLE 248 --- 249 // I will demo highlight below for the `main` function 250 /* adrdox_highlight{ */void main() { 251 252 }/* }adrdox_highlight */ 253 // and now we are done. 254 --- 255 ) 256 257 $(H4 Console macro - for console output) 258 259 The `$(CONSOLE)` macro is for copy/pasting text out of your console, such as showing command lines or program output. You MAY nest macros inside it for additional formatting, and thus, you should escape any `$` followed by `(` in the text. 260 261 $(ADRDOX_SAMPLE 262 $(CONSOLE 263 $ dmd hello.d 264 $ ./hello 265 Hello, $(B world)! 266 ) 267 ) 268 269 Note that most special syntax works inside `$(CONSOLE)`, but Ddoc-style code samples, delimited with `---`, does not. This is because that breaks things more often than it is useful. 270 271 $(H3 Documented unittests) 272 273 $(SIDEBAR Why does it allow inline examples? I often write full examples that I want to present in the prose, but I also like the compile check the unittests provide. So to get best of both worlds, I had to do it myself.) 274 275 I also implemented the feature from ddoc where unittests with a documentation comment are appended to the examples section of the previous documented declaration. They will appear in an `Examples` section (together with any others you manually write in `Examples:`), or inline in the documentation if you give them an `$(ID some_unique_name)` in the doc comment of the unittest, and write `$(EMBED_UNITTEST some_unique_name)` somewhere in your body text. Both the test and its associated comment will be moved to that location instead of being put in the examples section. 276 277 If you have a line that must be in the test to be useful, but should not appear in the documentation, you can simply comment it: `// exclude from docs`. But the line must end with that exact string. 278 279 --- 280 /// The assert inside will not appear in the generated docs 281 unittest { 282 int a; 283 assert(a == 2); // exclude from docs 284 writeln(a); 285 } 286 --- 287 288 $(H2 Cross-referencing) 289 290 Many tasks of cross-referencing are done automatically. Inheritance and function signatures use semantic data from the D source to link themselves. URLs in the raw text, such as http://dpldocs.info/ are detected and hyperlinked automatically. Tables of contents are created, as needed, by scanning for headers. 291 292 However, in your text, you may also want to reference names and links that are not automatically detected. 293 294 $(SIDEBAR It does not attempt to pick out D symbol names automatically from the text, since this leads to a great many false positives. ddoc's attempt to do this failed miserably.) 295 296 Since this is such a common task, I dedicated a short, special syntax to it: square brackets. Write a name or URL inside brackets and it will linkify it, as specifically as it can from the index built from semantic D data. For example: `[arsd.color]` will yield [arsd.color], a link to my color module. 297 298 When documenting code, it will first try to detect a URL. If so, it treats it as a link. Next, it will try to look up the D identifier in the current scope. If it finds it, it will link to the most local variable, following the import graph. If all else fails, it will just assume it is a relative filename and link that way. 299 300 $(NOTE 301 If you want to load modules for name lookup, but not generate documentation for them, pass 302 the file or the directory containing to `adrdox` with `--load`. 303 ) 304 305 In most cases, putting a D name inside brackets should link as you expect. 306 307 You can also change the display name by putting a pipe after the link, followed by text: `[arsd.color|my color module]` gives [arsd.color|my color module]. 308 309 Local sections can be referenced with `[#cross-referencing]`: [#cross-referencing]. 310 311 $(H3 Markdown-style links) 312 313 Markdown-style `[text](url)` links are also supported. There must be no space between the `]` and `(` and it must all appear on the same line. [My link here](http://dpldocs.info). Markdown-style links do $(B not) attempt name lookups like adrdox native `[links]`. 314 315 $(H3 User-defined attribues) 316 317 If you want a UDA to document its uses, you can add the magic macro `$(UDA_USES)` to it somewhere. This will list links to each symbol possessing the uda. 318 319 --- 320 /++ 321 This is used on: 322 323 $(UDA_USES) 324 +/ 325 enum MyUDA; 326 327 @MyUDA void foo() {} 328 --- 329 330 $(H2 Paragraph detection) 331 332 The generator will automatically handle paragraph tags by looking for blank lines and other separators. Just write and trust it to do the right thing. (If it doesn't, email me a bug report, please.) 333 334 $(H2 Images) 335 336 You can post images with `$(IMG source_url, alt text)`. The default CSS will put some reasonable size limits and margin on it. 337 338 The image will typically be hosted elsewhere, `IMG` simply takes a URL (though it can be a data url, you need to manage that yourself too). 339 340 FIXME: implement and document `$(LEFT )`, `$(RIGHT )`, and `$(CENTERED )`. 341 342 You may also use inline `$(SVG )` or `$(RAW_HTML)`. FIXME 343 344 Markdown-style `![alt text](url)` images are also supported, iff there are no spaces between the symbols and all appear on the same line. ![d logo](/d-logo.png). 345 346 Note that if the parens are not there, it is normal![1] (code there: `normal![1]`) 347 348 $(H2 Headers) 349 350 You can use ddoc-style macros for headers: `$(H1 Name of header)`, `$(H2 Subheader)`, and so on through `$(H6)`. Linking will be added automatically by the generator. 351 352 Custom ddoc sections (see below) are translated into `<h3>` headers. 353 354 You can also use a markdown style `====` under a line to trigger a header. These will render as `<h3>` if at top level, and `<h4>` if under a custom ddoc section (FIXME: that details is not yet implemented). For this to work: 355 356 $(LIST 357 * The header must be preceded by a blank line 358 * The `====` must be directly below the header 359 * The `====` must be followed by a blank line 360 * There must be at least 4 `=` on the line, and no other text (excluding whitespace). 361 ) 362 363 $(ADRDOX_SAMPLE 364 365 This is some text preceding the header. 366 367 This is the header 368 ================== 369 370 This is a paragraph under that header. 371 ) 372 373 Moreover, markdown style `## Header` are also supported. The number of `#` characters indicate the header level (1-6). Similar restrictions apply: 374 375 $(LIST 376 * The header must be preceded by and followed by a blank line 377 * The `#` must be the first non-whitespace character on the line 378 * There must be a space following the `#` characters. 379 ) 380 381 $(ADRDOX_SAMPLE 382 383 # H1 384 385 ## H2 386 387 ### H3 388 389 #not a header, missing space 390 391 a # is not a header 392 393 Nor is the following a header 394 # because it is not preceded by a blank line 395 ) 396 397 $(H3 Ddoc sections) 398 399 Most the Ddoc sections are supported too, and should be used where appropriate to document your code. I also added one called `diagnostics:`, where you can list common compile errors seen with the function. 400 401 `Examples:` (or `Example:`) is special in that documented unit tests are appended here. 402 403 You may define custom ddoc sections as long as they are all one word and includes at least one underscore in the name. They will be translated to `H3` headers, since they typically go under the `Detailed Description` H2-level header. 404 405 Be sure to correctly nest headers - put H3 under H2, and H4 under H3, etc. Failure to do so may break your table of contents. 406 407 $(ADRDOX_SAMPLE 408 $(H2 A header) 409 Some content 410 $(H3 Another header) 411 Some more content 412 413 A_Ddoc_Style_Header: 414 And some content 415 ) 416 417 418 $(H2 Content blocks) 419 420 There are a few content blocks to add boxes to your documentation: `$(TIP)`, `$(NOTE)`, `$(WARNING)`, `$(PITFALL)`, and `$(SIDEBAR)`. Inside these, you may write any content. 421 422 Use these boxes to make certain content stand out so the reader pays attention to something special (or, in the case of `SIDEBAR`, get out of the way so the reader can skip it). The intended semantics are: 423 424 `$(TIP)` is a cool fact to help you make the most of the code. 425 426 `$(NOTE)` is something the reader should be aware of, but they can get it wrong without major consequence. 427 428 `$(WARNING)` is something they need to watch out for, such as potential crashes or memory leaks when using the function. 429 430 `$(PITFALL)` is something that users very commonly get wrong and you want them to see it to avoid making the same mistake yet again. 431 432 `$(SIDEBAR)` will be typically displayed outside the flow of the text. It should be used when you want to expand on some details, but it isn't something the user strictly needs to know. 433 434 $(H2 Fancier Formatting) 435 436 $(SIDEBAR 437 $(H3 Why use macro syntax to bracket it instead of trying to detect like Markdown does?) 438 439 Basically, I have to support at least some of ddoc macro syntax anyway for compatibility with existing documents like Phobos, so it is a convenient thing to simplify my parser. 440 441 But, beyond that, it also gives me a chance to accept metadata, like class names to add to the HTML by putting them inside the block too. 442 ) 443 444 There are several magic macros that use domain-specific syntaxes for common formatting tasks, like lists and tables. The ddoc-style macro brackets the text, which is laid out in a particular way to make writing, reading, and editing the data most easy. 445 446 447 $(H3 Blockquotes) 448 449 Use the `$(BLOCKQUOTE)` macro to surround the quote. It will render as you expected. 450 451 $(ADRDOX_SAMPLE 452 $(BLOCKQUOTE 453 This is a quote! You can write whatever you want in here. 454 455 Including paragraphs, and other content. Unlike markdown, you 456 do not need to write `>` or spaces or anything else before every 457 line, instead you just wrap the whole thing in `$(BLOCKQUOTE)`. 458 459 If it has unbalanced parenthesis, you can use `$(LPAREN)` or `$(RPAREN)` 460 for them. 461 ) 462 ) 463 464 $(H3 Lists) 465 466 There are two types of list: `$(LIST)` and `$(NUMBERED_LIST)`. Both work the same way. The only difference is `$(LIST)` generates a `<ul>` tag, while `$(NUMBERED_LIST)` generates a `<ol>` tag. 467 468 Inside the magic list macros, a `*` character at the beginning of a line will create a new list item. 469 470 $(WARNING 471 Make sure the leading `*` does not line up with your comment marker, or the preprocessor may strip it thinking it is a comment in the style of: 472 473 --- 474 /** 475 * one of these 476 */ 477 --- 478 479 Since the preprocessor runs before analyzing brackets, it won't know that the star was intentional. 480 481 I recommend indenting your list stars by at least 4 spaces or one tab for best results. 482 ) 483 484 $(ADRDOX_SAMPLE 485 $(LIST 486 * List item 487 * Another list item 488 ) 489 490 $(NUMBERED_LIST 491 * One 492 * Two 493 * Three 494 ) 495 ) 496 497 Text inside the list items is processed normally. You may nest lists, have paragraphs inside them, or anything else. 498 499 $(TIP You can add a class name to the list element in the HTML by using the `$(CLASS)` magic macro before opening your first list item. Use this class, along with CSS, to apply custom style to the list and its items.) 500 501 You may also use `$(RAW_HTML)` for full control of the output, or legacy Ddoc style `$(UL $(LI ...))` macros to form lists as well. 502 503 $(H3 Tables) 504 505 I support two table syntaxes: list tables (by row and by column, inspired by reStructuredText) and compact tables, with optional ASCII art (inspired by Markdown). 506 507 $(H4 Compact Tables) 508 509 A compact table consists of an optional one-line caption, a one-line header row, and any number of one-line data rows. 510 511 Cells are separated with the `|` character. Empty cells at the beginning or end of the table are ignored, allowing you to draw an ASCII art border around the table if you like. 512 513 The first row is always considered the header row. Columns without header text are also considered header columns. 514 515 The minimal syntax to define a table is: 516 517 $(ADRDOX_SAMPLE 518 $(SMALL_TABLE 519 Basic table caption (this line is optional) 520 header 1|header 2 521 data 1|data 2 522 more data | more data 523 ) 524 ) 525 526 $(TIP Since the ddoc-style macro bracketing the table must have balanced parenthesis, any unbalanced parenthesis character inside should be put inside a $(BACKTICK)code block$(BACKTICK). You can also put pipe characters inside code blocks: 527 528 $(ADRDOX_SAMPLE 529 $(SMALL_TABLE 530 h1|h2 531 `d1|with pipe`|d2 532 ) 533 ) 534 ) 535 536 ASCII art inside the compact table is allowed, but not required. Any line that consists only of the characters `+-=|` is assumed to be decorative and ignored by the parser. Empty lines are also ignored. White space around your cells are also ignored. 537 538 The result is you can style it how you like. The following code will render the same way as the above table: 539 540 $(ADRDOX_SAMPLE 541 $(SMALL_TABLE 542 Basic table caption (this line is optional) 543 +-----------+-----------+ 544 | header 1 | header 2 | 545 +===========+===========+ 546 | data 1 | data 2 | 547 | more data | more data | 548 +-----------+-----------+ 549 ) 550 ) 551 552 $(H5 Two-dimensional tabular data) 553 554 If a table has an empty upper-left cell, it is assumed to have two axes. Cells under the column with the empty header are also rendered as headers. 555 556 Here is a two-dimensional table with and without the optional ascii art. 557 558 $(ADRDOX_SAMPLE 559 $(SMALL_TABLE 560 561 XOR Truth Table 562 +-----------+ 563 | | 0 | 1 | 564 +===|===|===+ 565 | 0 | F | T | 566 | 1 | T | F | 567 +-----------+ 568 ) 569 570 $(SMALL_TABLE 571 Alternative XOR 572 ||0|1 573 0|F|T 574 1|T|F 575 ) 576 ) 577 578 Notice that even without the ascii art, the outer pipe is necessary to indicate that an empty cell was intended in the upper left corner. 579 580 $(TIP 581 If you want to make a feature table, you can do it as a compact 582 table with any entry for yes, and no data for no. 583 584 $(ADRDOX_SAMPLE 585 $(SMALL_TABLE 586 Features 587 || x | y 588 a| * | 589 b| | * 590 c| * | * 591 ) 592 ) 593 594 You can then style these with CSS rules like `td:empty` in lieu of adding a class to each element. The empty cell on the right did not require an extra `|` because all data rows are assumed to have equal number of cells as the header row. 595 ) 596 597 $(H4 Longer tables) 598 599 I also support a list table format, inspired by restructuredText. 600 601 $(ADRDOX_SAMPLE 602 $(TABLE_ROWS 603 Caption 604 * + Header 1 605 + Header 2 606 * - Data 1 607 - Data 2 608 * - Data 1 609 - Data 2 610 ) 611 ) 612 613 In this format, the text before any `*` is the caption. Then, a leading `*` indicates a new row, a leading `+` starts a new table header, and a leading `-` starts a new table cell. The cells can be as long as you like. 614 615 adrdox will also detect if you put a header on the left side of later rows, and format the table accordingly: 616 617 $(ADRDOX_SAMPLE 618 $(TABLE_ROWS 619 Caption 620 * + Header 1 621 + Header 2 622 + Header 3 623 * + 2D Header 624 - Data 1.2 625 - Data 1.3 626 * + Again 627 - Data 1.2 628 - Data 2.3 629 ) 630 ) 631 632 633 634 $(H4 Formatting tables) 635 636 To format tables, including aligning text inside a column, add a class name to the tag using the magic `$(CLASS name)` macro right inside the table backeting, then target that with CSS rules in your stylesheet. 637 638 $(ADRDOX_SAMPLE 639 $(RAW_HTML 640 <style> 641 .my-yellow-table { 642 background-color: yellow; 643 } 644 </style> 645 ) 646 $(TABLE_ROWS 647 $(CLASS my-yellow-table) 648 Caption 649 * + Header 1 650 + Header 2 651 * - Data 1 652 - Data 2 653 * - Data 1 654 - Data 2 655 ) 656 ) 657 658 659 $(H4 More advanced tables) 660 661 To avoid complicating the syntax in more common cases, I do not attempt to support everything possible. Notably, most cases of colspan and rowspan cannot be expressed in any of my syntaxes. 662 663 If you need something, and all else fails, you can always use the `$(RAW_HTML)` escape hatch and write the code yourself. 664 665 $(H2 Mathematics) 666 667 The doc generator can also render LaTeX formulas, if latex and dvipng is installed on your system. 668 669 $(ADRDOX_SAMPLE 670 $(MATH \int_{1}^{\pi} \cos(x) dx ) 671 ) 672 673 Note that generating these images is kinda slow. You must balance parenthesis inside the macro, and all the output images will be rendered inline, packed in the html file. 674 675 If you can use a plain text or html character btw, you should. Don't break out MATH just for an $(INF) symbol, for example. 676 677 $(H2 Ddoc Macro to HTML Tag reference) 678 679 $(LIST 680 * `$(IMG source_url, alt text)` 681 * `$(B bold text)` 682 * `$(I italic text)` 683 * `$(U underlined text)` 684 * `$(SUPERSCRIPT superscript text)` 685 * `$(SUB subscript text)` 686 ) 687 688 $(H3 Adding ID and class attributes to HTML) 689 690 You can add an ID or class attribute to an HTML tag by putting `$(ID id_here)` or `$(CLASS class_here)` inside a ddoc macro. It must be inside a `$(ddoc_style)` macro to be recognized. 691 692 $(H2 Ddoc Sections) 693 694 $(H3 List of supported DDoc Sections) 695 696 $(LIST 697 * `Examples:` or `Example:` gives usage examples. Documented unittests, if present and not embedded (see [#documented-unittests]), will also appear here. 698 * `Bugs:` 699 * `See_Also:` 700 * `Returns:` 701 * `Throws:` 702 * `Deprecated:` 703 * `Params:` uses a special `name = comment` syntax, just like ddoc, where only param names detected are printed. 704 * `Macros:` are read, but ignored. 705 ) 706 707 $(H3 Meta subsections) 708 709 The following sections, if present, will be grouped under the `Meta` header: 710 711 $(LIST 712 * `Authors:` or `Author:` 713 * `Date` 714 * `License:` 715 * `Source:` 716 * `History:` 717 * `Credits:` 718 * `Standards:` 719 * `Copyright:` 720 * `Version:` 721 ) 722 723 $(H3 Adrdox extension sections) 724 725 $(LIST 726 * `Diagnostics:` is a place to describe common errors you will see while trying to use the function, and explain how to fix them. 727 * `Link_References:` does name=value. See [#footnotes]. 728 $(COMMENT * `Adrdox_Meta:` intrduces metadata for the generator. See [#metadata] ) 729 ) 730 731 $(H3 Custom sections) 732 733 If you start a line with `some_section:`, it will become a custom section in the document. It must have at least one underscore to be recognizes as a custom section. 734 735 $(COMMENT 736 $(H2 Metadata) 737 738 FIXME: NOT IMPLEMENTED 739 740 You can add metadata about your project to a `Adrdox_Meta:` section in the doc comment attached to the module declaration. These are inherited by submodules in your project as long as the package.d with the definition is loaded (see `--load` or passed as command line arg to be generated). 741 742 It can define: 743 $(LINK 744 * Project name 745 * Project logo image 746 * Project homepage 747 * Project color scheme: light or dark and accent color 748 * Scripts for the project 749 ) 750 ) 751 752 $(H2 Footnotes) 753 754 adrdox supports footnotes[1] and popup notes[2], scoped to the declaration attached to the comment. The syntax is to simply write `[n]`, such as `[1]`, where you want it to be displayed, then later in the comment, write a `Link_References:` section at the end of your comment, like so: 755 756 ``` 757 Link_References: 758 1 = https://en.wikipedia.org/wiki/Footnote 759 2 = This note will popup inline. 760 ``` 761 762 Undefined footnote references output the plain text without modification, like [3]. Numeric footnotes can only be used locally, they must be used and defined inside the same comment. 763 764 $(NOTE Text references must always be contained to a single line in the current implementation.) 765 766 If you need something more complex than a single link or line of text, write a section for your notes inside your comment and use the `[n]` Link_References to link to it: 767 768 --- 769 /++ 770 This huge complex function needs a complex footnote[1]. 771 772 $(H2 Footnotes) 773 774 $(DIV $(ID note-1) 775 This can be arbitrarily complex. 776 ) 777 778 Link_References: 779 1 = [a_huge_complex_function#note-1] 780 +/ 781 void a_huge_complex_function() {} 782 --- 783 784 See that live [a_huge_complex_function|here]. 785 786 You can also do custom links, images, or popup text via the shortcut `[reference]` syntax. You can define them with a symbol name in the Link_References section: 787 788 ``` 789 Link_References: 790 dlang = http://dlang.org/ 791 dlogo = $(IMG /d-logo.png, The D Logo) 792 dmotto = Modern convenience. Modeling power. Native efficiency. 793 ``` 794 795 You can now reference those with `[dlang], [dlogo], and [dmotto]`, which will render thusly: [dlang], [dlogo], [dmotto]. Be aware that ONLY a single line of plain text, a single `$(IMG)`, or a single link (url or convenience reference, see below) are allowed in the `Link_References` section. 796 797 $(NOTE 798 Link references will override D name lookup. Be aware of name clashes that might 799 break convenient access to in-scope symbol names. 800 ) 801 802 Like with other convenience links, you can change the displayed text by using a pipe character, like `[dlang|The D Website]`. It will continue to link to the same place or pop up the same text. If the name references an image, the text after the pipe will locally change the `alt` text on the image tag. 803 804 Additionally, the pipe character can be used in the reference definition to change the default display text: 805 806 ``` 807 Link_References: 808 input_range = [std.range.primitives.isInputRange|input range] 809 ``` 810 811 will always show "input range" when you write `[input_range]`, but can still be overridden by local text after the pipe, like `[input_range|an input range]`. Those will render: [input_range] and [input_range|an input range]. 812 813 $(TIP 814 Yes, you can define link references in terms of a D reference. It will look up the name using the normal scoping rules for the attached declaration. 815 ) 816 817 $(WARNING 818 If you use a reference in a global reference definition, it will look up the name in the scope at the *usage point*. This may change in the future. 819 ) 820 821 Unrecognized refs are forwarded to regular lookups. 822 823 While numeric link references are strictly scoped to the declaration of the attached comment, text link references are inherited by child declarations. Thus, you can define shortcuts at module scope and use them throughout the module. You can even define one in a package and use it throughout the package, without explicitly importing the `package.d` inside the module. Link references, however, are $(I not) imported like normal D symbols. They follow a strict parent->child inheritance. 824 825 If you need a link reference to be used over and over across packages, you may also define global link references in a text file you pass to adrdox with the `--link-references` option. The format of this text file is as follows: 826 827 ``` 828 name = value 829 othername = other value 830 ``` 831 832 Yes, the same as the `Link_References:` section inside a comment, but with no surrounding decoration. 833 834 $(PITFALL Be especially careful when defining global textual link macros, because they will override normal name lookups when doing `[convenient]` cross references across the entire current documentation build set.) 835 836 You may want to give unique, yet convenient names to common concepts used throughout your library and define them as Link_References for easy use. 837 838 Link_References: 839 1 = http://dpldocs.info/ 840 2 = Popup notes are done as <abbr> tags with title attributes. 841 input_range = [std.range.primitives.isInputRange|input range] 842 dlang = http://dlang.org/ 843 dlogo = $(IMG /d-logo.png, The D Logo) 844 dmotto = Modern convenience. Modeling power. Native efficiency. 845 846 $(H2 Side-by-side comparisons) 847 848 You might want to show two things side by side to emphasize how the user's existing knowledge can be shared. You can do that with the `$(SIDE_BY_SIDE $(COLUMN))` syntax: 849 850 $(ADRDOX_SAMPLE 851 $(SIDE_BY_SIDE 852 $(COLUMN 853 ```php 854 <?php 855 $foo = $_POST["foo"]; 856 ?> 857 ``` 858 ) 859 $(COLUMN 860 --- 861 import arsd.cgi; 862 string foo = cgi.post["foo"]; 863 --- 864 ) 865 ) 866 ) 867 868 Try to keep your columns as narrow as reasonable, so they can actually be read side-by-side! 869 870 $(H2 Commenting stuff out in comments) 871 872 The macro `$(COMMENT ...)` is removed from the generated document. You can use it to comment 873 stuff out of your comment. Of course, you can also just use regular `/*` comments instead of 874 `/**`. 875 876 $(H2 Always Documenting Something) 877 878 If you want something to always be documented, even if it is private, add `$(ALWAYS_DOCUMENT)` to its comment somewhere. 879 880 $(H2 Documentable Constructs) 881 882 adrdox allows documenting more language constructs than ddoc. It lets you document public imports, postblits, destructors, anonymous enums, and more. Try putting a doc comment on almost anything and see what happens! 883 884 +/ 885 module adrdox.syntax; 886 887 /+ 888 /// penis 889 struct A { 890 /// vagina 891 union { 892 /// ass 893 int a; 894 /// hole 895 int b; 896 } 897 } 898 +/ 899 900 901 /* 902 903 $(H3 Code with output) 904 905 The magic macro `$(CODE_WITH_OUTPUT)` is used to pair a block of code with a block of output, side-by-side. The first code block in the macro is considered the code, and the rest of the content is the output. 906 907 As a special case, if the code is of the `adrdox` language, you do not need to provide output; it will render automatically. (I added that feature to make writing this document easer.) I might add other language filters too, probably by piping it out to some command line, if there's demand for it. 908 909 I intend for this to be used to show syntax translations, but any time where a side-by-side view may be useful you can give it a try. 910 911 */ 912 /++ 913 This huge complex function needs a complex footnote[1]. 914 915 $(H2 Footnotes) 916 917 $(DIV $(ID note-1) 918 This can be arbitrarily complex. 919 ) 920 921 Link_References: 922 1 = [a_huge_complex_function#note-1] 923 +/ 924 void a_huge_complex_function() {}