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 ```sdlang 219 // dub.sdl can contain comments! 220 name "somepackage" 221 description "A little web service of mine." 222 authors "Peter Parker" 223 homepage "http://myproject.example.com" 224 license "GPL-2.0" 225 dependency "vibe-d" version="~>0.7.23" 226 configuration "metro-app" { 227 platforms "windows" 228 targetType "executable" 229 versions "MetroApp" 230 libs "d3d11" 231 } 232 configuration "desktop-app" { 233 platforms "windows" 234 targetType "executable" 235 versions "DesktopApp" 236 libs "d3d9" 237 } 238 configuration "glut-app" { 239 // works on any platform 240 targetType "executable" 241 versions "GlutApp" 242 } 243 ``` 244 ) 245 246 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. 247 248 Use the language name in all lower case when tagging the language, like `php` or `c++`. 249 250 $(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.) 251 252 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. 253 254 $(H4 Ddoc style - for D code) 255 256 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. 257 258 $(ADRDOX_SAMPLE 259 --- 260 /** 261 Ddoc style code blocks understand D deeply. 262 263 --- 264 if(example.nested) 265 stillWorks!(); 266 --- 267 */ 268 void main() {} 269 --- 270 ) 271 272 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). 273 274 $(ADRDOX_SAMPLE 275 --- 276 // I will demo highlight below for the `main` function 277 /* adrdox_highlight{ */void main() { 278 279 }/* }adrdox_highlight */ 280 // and now we are done. 281 --- 282 ) 283 284 $(H4 Console macro - for console output) 285 286 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. 287 288 $(ADRDOX_SAMPLE 289 $(CONSOLE 290 $ dmd hello.d 291 $ ./hello 292 Hello, $(B world)! 293 ) 294 ) 295 296 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. 297 298 $(H3 Documented unittests) 299 300 $(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.) 301 302 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. 303 304 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. 305 306 --- 307 /// The assert inside will not appear in the generated docs 308 unittest { 309 int a; 310 assert(a == 2); // exclude from docs 311 writeln(a); 312 } 313 --- 314 315 $(H2 Cross-referencing) 316 317 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. 318 319 However, in your text, you may also want to reference names and links that are not automatically detected. 320 321 $(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.) 322 323 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. 324 325 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. 326 327 $(NOTE 328 If you want to load modules for name lookup, but not generate documentation for them, pass 329 the file or the directory containing to `adrdox` with `--load`. 330 ) 331 332 In most cases, putting a D name inside brackets should link as you expect. 333 334 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]. 335 336 Local sections can be referenced with `[#cross-referencing]`: [#cross-referencing]. 337 338 $(H3 Markdown-style links) 339 340 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]`. 341 342 $(H3 User-defined attribues) 343 344 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. 345 346 --- 347 /++ 348 This is used on: 349 350 $(UDA_USES) 351 +/ 352 enum MyUDA; 353 354 @MyUDA void foo() {} 355 --- 356 357 $(H2 Paragraph detection) 358 359 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.) 360 361 $(H2 Images) 362 363 You can post images with `$(IMG source_url, alt text)`. The default CSS will put some reasonable size limits and margin on it. 364 365 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). 366 367 FIXME: implement and document `$(LEFT )`, `$(RIGHT )`, and `$(CENTERED )`. 368 369 You may also use inline `$(SVG )` or `$(RAW_HTML)`. FIXME 370 371 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). 372 373 Note that if the parens are not there, it is normal![1] (code there: `normal![1]`) 374 375 $(H2 Headers) 376 377 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. 378 379 Custom ddoc sections (see below) are translated into `<h3>` headers. 380 381 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: 382 383 $(LIST 384 * The header must be preceded by a blank line 385 * The `====` must be directly below the header 386 * The `====` must be followed by a blank line 387 * There must be at least 4 `=` on the line, and no other text (excluding whitespace). 388 ) 389 390 $(ADRDOX_SAMPLE 391 392 This is some text preceding the header. 393 394 This is the header 395 ================== 396 397 This is a paragraph under that header. 398 ) 399 400 Moreover, markdown style `## Header` are also supported. The number of `#` characters indicate the header level (1-6). Similar restrictions apply: 401 402 $(LIST 403 * The header must be preceded by and followed by a blank line 404 * The `#` must be the first non-whitespace character on the line 405 * There must be a space following the `#` characters. 406 ) 407 408 $(ADRDOX_SAMPLE 409 410 # H1 411 412 ## H2 413 414 ### H3 415 416 #not a header, missing space 417 418 a # is not a header 419 420 Nor is the following a header 421 # because it is not preceded by a blank line 422 ) 423 424 $(H3 Ddoc sections) 425 426 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. 427 428 `Examples:` (or `Example:`) is special in that documented unit tests are appended here. 429 430 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. 431 432 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. 433 434 $(ADRDOX_SAMPLE 435 $(H2 A header) 436 Some content 437 $(H3 Another header) 438 Some more content 439 440 A_Ddoc_Style_Header: 441 And some content 442 ) 443 444 445 $(H2 Content blocks) 446 447 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. 448 449 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: 450 451 `$(TIP)` is a cool fact to help you make the most of the code. 452 453 `$(NOTE)` is something the reader should be aware of, but they can get it wrong without major consequence. 454 455 `$(WARNING)` is something they need to watch out for, such as potential crashes or memory leaks when using the function. 456 457 `$(PITFALL)` is something that users very commonly get wrong and you want them to see it to avoid making the same mistake yet again. 458 459 `$(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. 460 461 $(H2 Fancier Formatting) 462 463 $(SIDEBAR 464 $(H3 Why use macro syntax to bracket it instead of trying to detect like Markdown does?) 465 466 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. 467 468 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. 469 ) 470 471 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. 472 473 474 $(H3 Blockquotes) 475 476 Use the `$(BLOCKQUOTE)` macro to surround the quote. It will render as you expected. 477 478 $(ADRDOX_SAMPLE 479 $(BLOCKQUOTE 480 This is a quote! You can write whatever you want in here. 481 482 Including paragraphs, and other content. Unlike markdown, you 483 do not need to write `>` or spaces or anything else before every 484 line, instead you just wrap the whole thing in `$(BLOCKQUOTE)`. 485 486 If it has unbalanced parenthesis, you can use `$(LPAREN)` or `$(RPAREN)` 487 for them. 488 ) 489 ) 490 491 $(H3 Lists) 492 493 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. 494 495 Inside the magic list macros, a `*` character at the beginning of a line will create a new list item. 496 497 $(WARNING 498 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: 499 500 --- 501 /** 502 * one of these 503 */ 504 --- 505 506 Since the preprocessor runs before analyzing brackets, it won't know that the star was intentional. 507 508 I recommend indenting your list stars by at least 4 spaces or one tab for best results. 509 ) 510 511 $(ADRDOX_SAMPLE 512 $(LIST 513 * List item 514 * Another list item 515 ) 516 517 $(NUMBERED_LIST 518 * One 519 * Two 520 * Three 521 ) 522 ) 523 524 Text inside the list items is processed normally. You may nest lists, have paragraphs inside them, or anything else. 525 526 $(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.) 527 528 You may also use `$(RAW_HTML)` for full control of the output, or legacy Ddoc style `$(UL $(LI ...))` macros to form lists as well. 529 530 $(H3 Tables) 531 532 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). 533 534 $(H4 Compact Tables) 535 536 A compact table consists of an optional one-line caption, a one-line header row, and any number of one-line data rows. 537 538 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. 539 540 The first row is always considered the header row. Columns without header text are also considered header columns. 541 542 The minimal syntax to define a table is: 543 544 $(ADRDOX_SAMPLE 545 $(SMALL_TABLE 546 Basic table caption (this line is optional) 547 header 1|header 2 548 data 1|data 2 549 more data | more data 550 ) 551 ) 552 553 $(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: 554 555 $(ADRDOX_SAMPLE 556 $(SMALL_TABLE 557 h1|h2 558 `d1|with pipe`|d2 559 ) 560 ) 561 ) 562 563 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. 564 565 The result is you can style it how you like. The following code will render the same way as the above table: 566 567 $(ADRDOX_SAMPLE 568 $(SMALL_TABLE 569 Basic table caption (this line is optional) 570 +-----------+-----------+ 571 | header 1 | header 2 | 572 +===========+===========+ 573 | data 1 | data 2 | 574 | more data | more data | 575 +-----------+-----------+ 576 ) 577 ) 578 579 $(H5 Two-dimensional tabular data) 580 581 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. 582 583 Here is a two-dimensional table with and without the optional ascii art. 584 585 $(ADRDOX_SAMPLE 586 $(SMALL_TABLE 587 588 XOR Truth Table 589 +-----------+ 590 | | 0 | 1 | 591 +===|===|===+ 592 | 0 | F | T | 593 | 1 | T | F | 594 +-----------+ 595 ) 596 597 $(SMALL_TABLE 598 Alternative XOR 599 ||0|1 600 0|F|T 601 1|T|F 602 ) 603 ) 604 605 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. 606 607 $(TIP 608 If you want to make a feature table, you can do it as a compact 609 table with any entry for yes, and no data for no. 610 611 $(ADRDOX_SAMPLE 612 $(SMALL_TABLE 613 Features 614 || x | y 615 a| * | 616 b| | * 617 c| * | * 618 ) 619 ) 620 621 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. 622 ) 623 624 $(H4 Longer tables) 625 626 I also support a list table format, inspired by restructuredText. 627 628 $(ADRDOX_SAMPLE 629 $(TABLE_ROWS 630 Caption 631 * + Header 1 632 + Header 2 633 * - Data 1 634 - Data 2 635 * - Data 1 636 - Data 2 637 ) 638 ) 639 640 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. 641 642 adrdox will also detect if you put a header on the left side of later rows, and format the table accordingly: 643 644 $(ADRDOX_SAMPLE 645 $(TABLE_ROWS 646 Caption 647 * + Header 1 648 + Header 2 649 + Header 3 650 * + 2D Header 651 - Data 1.2 652 - Data 1.3 653 * + Again 654 - Data 1.2 655 - Data 2.3 656 ) 657 ) 658 659 660 661 $(H4 Formatting tables) 662 663 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. 664 665 $(ADRDOX_SAMPLE 666 $(RAW_HTML 667 <style> 668 .my-yellow-table { 669 background-color: yellow; 670 } 671 </style> 672 ) 673 $(TABLE_ROWS 674 $(CLASS my-yellow-table) 675 Caption 676 * + Header 1 677 + Header 2 678 * - Data 1 679 - Data 2 680 * - Data 1 681 - Data 2 682 ) 683 ) 684 685 686 $(H4 More advanced tables) 687 688 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. 689 690 If you need something, and all else fails, you can always use the `$(RAW_HTML)` escape hatch and write the code yourself. 691 692 $(H2 Mathematics) 693 694 The doc generator can also render LaTeX formulas, if latex and dvipng is installed on your system. 695 696 $(ADRDOX_SAMPLE 697 $(MATH \int_{1}^{\pi} \cos(x) dx ) 698 ) 699 700 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. 701 702 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. 703 704 $(H2 Ddoc Macro to HTML Tag reference) 705 706 $(LIST 707 * `$(IMG source_url, alt text)` 708 * `$(B bold text)` 709 * `$(I italic text)` 710 * `$(U underlined text)` 711 * `$(SUPERSCRIPT superscript text)` 712 * `$(SUB subscript text)` 713 ) 714 715 $(H3 Adding ID and class attributes to HTML) 716 717 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. 718 719 $(H2 Ddoc Sections) 720 721 $(H3 List of supported DDoc Sections) 722 723 $(LIST 724 * `Examples:` or `Example:` gives usage examples. Documented unittests, if present and not embedded (see [#documented-unittests]), will also appear here. 725 * `Bugs:` 726 * `See_Also:` 727 * `Returns:` 728 * `Throws:` 729 * `Deprecated:` 730 * `Params:` uses a special `name = comment` syntax, just like ddoc, where only param names detected are printed. 731 * `Macros:` are read, but ignored. 732 ) 733 734 $(H3 Meta subsections) 735 736 The following sections, if present, will be grouped under the `Meta` header: 737 738 $(LIST 739 * `Authors:` or `Author:` 740 * `Date` 741 * `License:` 742 * `Source:` 743 * `History:` 744 * `Credits:` 745 * `Standards:` 746 * `Copyright:` 747 * `Version:` 748 ) 749 750 $(H3 Adrdox extension sections) 751 752 $(LIST 753 * `Diagnostics:` is a place to describe common errors you will see while trying to use the function, and explain how to fix them. 754 * `Link_References:` does name=value. See [#footnotes]. 755 $(COMMENT * `Adrdox_Meta:` intrduces metadata for the generator. See [#metadata] ) 756 ) 757 758 $(H3 Custom sections) 759 760 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. 761 762 $(COMMENT 763 $(H2 Metadata) 764 765 FIXME: NOT IMPLEMENTED 766 767 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). 768 769 It can define: 770 $(LINK 771 * Project name 772 * Project logo image 773 * Project homepage 774 * Project color scheme: light or dark and accent color 775 * Scripts for the project 776 ) 777 ) 778 779 $(H2 Footnotes) 780 781 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: 782 783 ``` 784 Link_References: 785 1 = https://en.wikipedia.org/wiki/Footnote 786 2 = This note will popup inline. 787 ``` 788 789 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. 790 791 $(NOTE Text references must always be contained to a single line in the current implementation.) 792 793 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: 794 795 --- 796 /++ 797 This huge complex function needs a complex footnote[1]. 798 799 $(H2 Footnotes) 800 801 $(DIV $(ID note-1) 802 This can be arbitrarily complex. 803 ) 804 805 Link_References: 806 1 = [a_huge_complex_function#note-1] 807 +/ 808 void a_huge_complex_function() {} 809 --- 810 811 See that live [a_huge_complex_function|here]. 812 813 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: 814 815 ``` 816 Link_References: 817 dlang = http://dlang.org/ 818 dlogo = $(IMG /d-logo.png, The D Logo) 819 dmotto = Modern convenience. Modeling power. Native efficiency. 820 ``` 821 822 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. 823 824 $(NOTE 825 Link references will override D name lookup. Be aware of name clashes that might 826 break convenient access to in-scope symbol names. 827 ) 828 829 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. 830 831 Additionally, the pipe character can be used in the reference definition to change the default display text: 832 833 ``` 834 Link_References: 835 input_range = [std.range.primitives.isInputRange|input range] 836 ``` 837 838 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]. 839 840 $(TIP 841 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. 842 ) 843 844 $(WARNING 845 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. 846 ) 847 848 Unrecognized refs are forwarded to regular lookups. 849 850 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. 851 852 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: 853 854 ``` 855 name = value 856 othername = other value 857 ``` 858 859 Yes, the same as the `Link_References:` section inside a comment, but with no surrounding decoration. 860 861 $(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.) 862 863 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. 864 865 Link_References: 866 1 = http://dpldocs.info/ 867 2 = Popup notes are done as <abbr> tags with title attributes. 868 input_range = [std.range.primitives.isInputRange|input range] 869 dlang = http://dlang.org/ 870 dlogo = $(IMG /d-logo.png, The D Logo) 871 dmotto = Modern convenience. Modeling power. Native efficiency. 872 873 $(H2 Side-by-side comparisons) 874 875 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: 876 877 $(ADRDOX_SAMPLE 878 $(SIDE_BY_SIDE 879 $(COLUMN 880 ```php 881 <?php 882 $foo = $_POST["foo"]; 883 ?> 884 ``` 885 ) 886 $(COLUMN 887 --- 888 import arsd.cgi; 889 string foo = cgi.post["foo"]; 890 --- 891 ) 892 ) 893 ) 894 895 Try to keep your columns as narrow as reasonable, so they can actually be read side-by-side! 896 897 $(H2 Commenting stuff out in comments) 898 899 The macro `$(COMMENT ...)` is removed from the generated document. You can use it to comment 900 stuff out of your comment. Of course, you can also just use regular `/*` comments instead of 901 `/**`. 902 903 $(H2 Always Documenting Something) 904 905 If you want something to always be documented, even if it is private, add `$(ALWAYS_DOCUMENT)` to its comment somewhere. 906 907 $(H2 Documentable Constructs) 908 909 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! 910 911 +/ 912 module adrdox.syntax; 913 914 /+ 915 /// penis 916 struct A { 917 /// vagina 918 union { 919 /// ass 920 int a; 921 /// hole 922 int b; 923 } 924 } 925 +/ 926 927 928 /* 929 930 $(H3 Code with output) 931 932 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. 933 934 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. 935 936 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. 937 938 */ 939 /++ 940 This huge complex function needs a complex footnote[1]. 941 942 $(H2 Footnotes) 943 944 $(DIV $(ID note-1) 945 This can be arbitrarily complex. 946 ) 947 948 Link_References: 949 1 = [a_huge_complex_function#note-1] 950 +/ 951 void a_huge_complex_function() {}