"Fossies" - the Fresh Open Source Software Archive

Member "dmd2/html/d/spec/ddoc.html" (20 Nov 2020, 77705 Bytes) of package /linux/misc/dmd.2.094.2.linux.tar.xz:

The requested HTML page contains a <FORM> tag that is unusable on "Fossies" in "automatic" (rendered) mode so that page is shown as HTML source code syntax highlighting (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file.

    2 <!DOCTYPE html>
    3 <html lang="en-US">
    4 <!--
    5     Copyright (c) 1999-2020 by the D Language Foundation
    6     All Rights Reserved.
    7     https://dlang.org/foundation_overview.html
    8   -->
    9 <head>
   10 <meta charset="utf-8">
   11 <meta name="keywords" content="D programming language">
   12 <meta name="description" content="D Programming Language">
   13 <title>Documentation Generator - D Programming Language</title>
   15 <link rel="stylesheet" href="../css/codemirror.css">
   16 <link rel="stylesheet" href="../css/style.css">
   17 <link rel="stylesheet" href="../css/print.css" media="print">
   18 <link rel="shortcut icon" href="../favicon.ico">
   19 <meta name="viewport" content="width=device-width, initial-scale=1.0, minimum-scale=0.1, maximum-scale=10.0">
   21 </head>
   22 <body id='Documentation Generator' class='doc'>
   23 <script type="text/javascript">document.body.className += ' have-javascript'</script>
   24 <div id="top"><div class="helper"><div class="helper expand-container">    <div class="logo"><a href=".."><img id="logo" alt="D Logo" src="../images/dlogo.svg"></a></div>
   25     <a href="../menu.html" title="Menu" class="hamburger expand-toggle"><span>Menu</span></a>
   27 <div id="cssmenu"><ul>    <li><a href='https://tour.dlang.org'><span>Learn</span></a></li>
   28     <li class='expand-container'><a class='expand-toggle' href='../documentation.html'><span>Documentation</span></a>
   30 <ul class='expand-content'>    <li><a href='../spec/spec.html'>Language Reference</a></li>
   31     <li><a href='../phobos/index.html'>Library Reference</a></li>
   32     <li><a href='../dmd.html'>Command-line Reference</a></li>
   33     <li class="menu-divider"><a href='../comparison.html'>Feature Overview</a></li>
   34     <li><a href='../articles.html'>Articles</a></li>
   35  </ul></li>
   36     <li><a href='../download.html'><span>Downloads</span></a></li>
   37     <li><a href='https://code.dlang.org'><span>Packages</span></a></li>
   38     <li class='expand-container'><a class='expand-toggle' href='../community.html'><span>Community</span></a>
   40 <ul class='expand-content'>    <li><a href='https://dlang.org/blog'>Blog</a></li>
   41     <li><a href='../orgs-using-d.html'>Orgs using D</a></li>
   42     <li><a href='https://twitter.com/search?q=%23dlang'>Twitter</a></li>
   43     <li><a href='../calendar.html'>Calendar</a></li>
   44     <li class="menu-divider"><a href='https://forum.dlang.org'>Forums</a></li>
   45     <li><a href='irc://irc.freenode.net/d'>IRC</a></li>
   46     <li><a href='https://discord.gg/bMZk9Q4'>Community Discord</a></li>
   47     <li><a href='https://wiki.dlang.org'>Wiki</a></li>
   48     <li class="menu-divider"><a href='https://github.com/dlang'>GitHub</a></li>
   49     <li><a href='../bugstats.html'>Issues</a></li>
   50     <li><a href='https://wiki.dlang.org/Get_involved'>Get involved</a></li>
   51     <li class="menu-divider"><a href='../foundation/contributors.html'>Contributors</a></li>
   52     <li><a href='../foundation/index.html'>Foundation</a></li>
   53     <li><a href='..//security.html'>Security Team</a></li>
   54     <li><a href='../foundation/donate.html'>Donate</a></li>
   55     <li><a href='../foundation/sponsors.html'>Sponsors</a></li>
   56  </ul></li>
   57     <li class='expand-container'><a class='expand-toggle' href='../resources.html'><span>Resources</span></a>
   59 <ul class='expand-content'>    <li><a href='https://tour.dlang.org'>Tour</a></li>
   60     <li><a href='https://wiki.dlang.org/Books'>Books</a></li>
   61     <li><a href='https://wiki.dlang.org/Tutorials'>Tutorials</a></li>
   62     <li class="menu-divider"><a href='https://wiki.dlang.org/Development_tools'>Tools</a></li>
   63     <li><a href='https://wiki.dlang.org/Editors'>Editors</a></li>
   64     <li><a href='https://wiki.dlang.org/IDEs'>IDEs</a></li>
   65     <li><a href='https://run.dlang.io'>run.dlang.io</a></li>
   66     <li><a href='http://rainers.github.io/visuald/visuald/StartPage.html'>Visual D</a></li>
   67     <li class="menu-divider"><a href='../acknowledgements.html'>Acknowledgments</a></li>
   68     <li><a href='../dstyle.html'>D Style</a></li>
   69     <li><a href='../glossary.html'>Glossary</a></li>
   70     <li><a href='../sitemap.html'>Sitemap</a></li>
   71  </ul></li>
   72 </ul></div>
   73     <div class="search-container expand-container">        <a href="../search.html" class="expand-toggle" title="Search"><span>Search</span></a>
   75     <div id="search-box">        <form method="get" action="https://google.com/search">
   76             <input type="hidden" id="domains" name="domains" value="dlang.org">
   77             <input type="hidden" id="sourceid" name="sourceid" value="google-search">
   78             <span id="search-query"><input id="q" name="q" placeholder="Search"></span><span id="search-dropdown"><span class="helper">                <select id="sitesearch" name="sitesearch" size="1">
   79                     <option value="dlang.org">Entire Site</option>
   80                     <option selected value="dlang.org/spec">Language</option>
   81                     <option  value="dlang.org/phobos">Library</option>
   82                     <option  value="forum.dlang.org">Forums</option>
   84                 </select>
   85             </span></span><span id="search-submit"><button type="submit"><i class="fa fa-search"></i><span>go</span></button></span>
   86         </form>
   87     </div>
   88     </div>
   89 </div></div></div>
   91 <div class="container">    
   92 <div class="subnav-helper"></div> <div class="subnav">    <div class="head"><h5>Language Reference</h5> <p class="subnav-duplicate"><a href="../spec/spec.html">table of contents</a></p></div>
   93     <ul>        <li><a href='            ../spec/intro.html'>Introduction</a></li><li><a href='            ../spec/lex.html'>Lexical</a></li><li><a href='            ../spec/grammar.html'>Grammar</a></li><li><a href='            ../spec/module.html'>Modules</a></li><li><a href='            ../spec/declaration.html'>Declarations</a></li><li><a href='            ../spec/type.html'>Types</a></li><li><a href='            ../spec/property.html'>Properties</a></li><li><a href='            ../spec/attribute.html'>Attributes</a></li><li><a href='            ../spec/pragma.html'>Pragmas</a></li><li><a href='            ../spec/expression.html'>Expressions</a></li><li><a href='            ../spec/statement.html'>Statements</a></li><li><a href='            ../spec/arrays.html'>Arrays</a></li><li><a href='            ../spec/hash-map.html'>Associative Arrays</a></li><li><a href='            ../spec/struct.html'>Structs and Unions</a></li><li><a href='            ../spec/class.html'>Classes</a></li><li><a href='            ../spec/interface.html'>Interfaces</a></li><li><a href='            ../spec/enum.html'>Enums</a></li><li><a href='            ../spec/const3.html'>Type Qualifiers</a></li><li><a href='            ../spec/function.html'>Functions</a></li><li><a href='            ../spec/operatoroverloading.html'>Operator Overloading</a></li><li><a href='            ../spec/template.html'>Templates</a></li><li><a href='            ../spec/template-mixin.html'>Template Mixins</a></li><li><a href='            ../spec/contracts.html'>Contract Programming</a></li><li><a href='            ../spec/version.html'>Conditional Compilation</a></li><li><a href='            ../spec/traits.html'>Traits</a></li><li><a href='            ../spec/errors.html'>Error Handling</a></li><li><a href='            ../spec/unittest.html'>Unit Tests</a></li><li><a href='            ../spec/garbage.html'>Garbage Collection</a></li><li><a href='            ../spec/float.html'>Floating Point</a></li><li><a href='            ../spec/iasm.html'>D x86 Inline Assembler</a></li><li><a href='            ../spec/ddoc.html'>Embedded Documentation</a></li><li><a href='            ../spec/interfaceToC.html'>Interfacing to C</a></li><li><a href='            ../spec/cpp_interface.html'>Interfacing to C++</a></li><li><a href='            ../spec/objc_interface.html'>Interfacing to Objective-C</a></li><li><a href='            ../spec/portability.html'>Portability Guide</a></li><li><a href='            ../spec/entity.html'>Named Character Entities</a></li><li><a href='            ../spec/memory-safe-d.html'>Memory Safety</a></li><li><a href='            ../spec/abi.html'>Application Binary Interface</a></li><li><a href='            ../spec/simd.html'>Vector Extensions</a></li><li><a href='            ../spec/betterc.html'>Better C</a></li><li><a href='            ../spec/ob.html'>Live Functions
   94         </a></li>
   95     </ul>
   96 </div>
   97     <div class="hyphenate" id="content">        
   98 <div id="tools"><div >  <div class="tip smallprint">        <a href="https://issues.dlang.org/enter_bug.cgi?bug_file_loc=http%3A%2F%2Fdlang.org/&amp;component=dlang.org&amp;op_sys=All&amp;priority=P3&amp;product=D&amp;rep_platform=All&amp;short_desc=%5BDocumentation Generator%5D&amp;version=D2&amp;bug_severity=enhancement">Report a bug</a>
   99         <div >          If you spot a problem with this page, click here to create a Bugzilla issue.
  100         </div>
  101     </div>
  102     <div class="tip smallprint">        <a href="https://github.com/dlang/dlang.org/edit/master/spec/ddoc.dd">Improve this page</a>
  103         <div >          Quickly fork, edit online, and submit a pull request for this page.
  104             Requires a signed-in GitHub account. This works well for small changes.
  105             If you'd like to make larger changes you may want to consider using
  106             a local clone.
  107         </div>
  108     </div>
  109 </div></div>
  110         <h1>Documentation Generator</h1>
  112 <style>    body { counter-reset: h1 31; counter-increment: h1 -1; }
  113     h1 { counter-reset: h2 h3 p; }
  114     h2 { counter-reset: h3 h4 p; }
  115     h3 { counter-reset: h4 p; }
  116     h4 { counter-reset: p; }
  117     h1::before {
  118         counter-increment: h1;
  119         content: counter(h1) ". ";
  120     }
  121     h2::before {
  122         counter-increment: h2;
  123         content: counter(h1) "." counter(h2) " ";
  124     }
  125     h3::before {
  126         counter-increment: h3;
  127         content: counter(h1) "." counter(h2) "." counter(h3) " ";
  128     }
  129     h4::before {
  130         counter-increment: h4;
  131         content: counter(h1) "." counter(h2) "." counter(h3) "." counter(h4) " ";
  132     }
  133     p::before, .spec-boxes::before {
  134         counter-increment: p;
  135         content: counter(p) ". ";
  136     }
  137     h1::before, h2::before, h3::before, h4::before, p::before, .spec-boxes::before
  138     {
  139         color: #999;
  140         font-size: 80%;
  141         margin-right: 0.25em;
  142     }
  143 </style>
  144         <div class="blankline"></div>
  145 <div class="blankline"></div>
  146 <div class="blankline"></div>
  147 <div class="page-contents quickindex">    <div class="page-contents-header">        <b>Contents</b>
  148     </div>
  149     <ol>    <li><a href="#specifications">Specification</a><ol>        <li><a href="#phases_of_processing">Phases of Processing</a></li>
  150         <li><a href="#lexical">Lexical</a></li>
  151         <li><a href="#parsing">Parsing</a></li>
  152         <li><a href="#sections">Sections</a></li>
  153         <li><a href="#standard_sections">Standard Sections</a></li>
  154         <li><a href="#special_sections">Special Sections</a></li>
  155     </ol></li>
  156     <li><a href="#highlighting">Highlighting</a><ol>        <li><a href="#embedded_comments">Embedded Comments</a></li>
  157         <li><a href="#embedded_code">Embedded Code</a></li>
  158         <li><a href="#inline_code">Inline Code</a></li>
  159         <li><a href="#embedded_html">Embedded HTML</a></li>
  160         <li><a href="#headings">Headings</a></li>
  161         <li><a href="#links">Links</a></li>
  162         <li><a href="#lists">Lists</a></li>
  163         <li><a href="#tables">Tables</a></li>
  164         <li><a href="#quotes">Quotes</a></li>
  165         <li><a href="#hrules">Horizontal Rules</a></li>
  166         <li><a href="#text_emphasis">Text Emphasis</a></li>
  167         <li><a href="#emphasis">Identifier Emphasis</a></li>
  168         <li><a href="#character_entities">Character Entities</a></li>
  169         <li><a href="#punctuation_escapes">Punctuation Escapes</a></li>
  170         <li><a href="#no_documentation">No Documentation</a></li>
  171     </ol></li>
  172     <li><a href="#macros">Macros</a><ol>        <li><a href="#predefined_macros">Predefined Macros</a></li>
  173         <li><a href="#macro_def_scini">Macro Definitions from <span class="d_inlinecode donthyphenate notranslate">sc.ini</span>'s DDOCFILE</a></li>
  174         <li><a href="#macro_def_ddoc_file">Macro Definitions from .ddoc Files on the Command Line</a></li>
  175         <li><a href="#macro_def_ddocgenerated">Macro Definitions Generated by Ddoc</a></li>
  176     </ol></li>
  177     <li><a href="#using_ddoc_to_generate_examples">Using Ddoc to generate examples from unit tests</a></li>
  178     <li><a href="#using_ddoc_for_other_documentation">Using Ddoc for other Documentation</a></li>
  179     <li><a href="#security">Security considerations</a></li>
  180     <li><a href="#links_to_d_documentation_generators">Links to D documentation generators</a></li>
  181 </ol>
  182 </div>
  183 <div class="blankline"></div>
  184 <p>The D programming language enables embedding both contracts and test
  185 code along side the actual code, which helps to keep them all
  186 consistent with each other. One thing lacking is the documentation,
  187 as ordinary comments are usually unsuitable for automated extraction
  188 and formatting into manual pages.
  189 Embedding the user documentation into the source code has important
  190 advantages, such as not having to write the documentation twice, and
  191 the likelihood of the documentation staying consistent with the code.
  192 </p>
  193 <div class="blankline"></div>
  194 <p>Some existing approaches to this are:
  195 </p>
  196 <div class="blankline"></div>
  197 <ul><li><a href="http://www.stack.nl/~dimitri/doxygen">Doxygen</a> which already has some support for D</li>
  198 <li>Java's <a href="https://docs.oracle.com/javase/7/docs/technotes/guides/javadoc/index.html">Javadoc</a>,
  199  probably the most well-known</li>
  200 <li>C#'s <a href="https://msdn.microsoft.com/en-us/library/b2s063f7.aspx">embedded XML</a></li>
  201 <li>Other <a href="https://python.org/sigs/doc-sig/otherlangs.html">documentation tools</a></li>
  202 </ul>
  203 <div class="blankline"></div>
  204 <p>D's goals for embedded documentation are:
  205 </p>
  206 <div class="blankline"></div>
  207 <ol>    <li>It looks good as embedded documentation, not just after it
  208     is extracted and processed.</li>
  209     <li>It's easy and natural to write,
  210     i.e. minimal reliance on &lt;tags&gt; and other clumsy forms one
  211     would never see in a finished document.</li>
  212     <li>It does not repeat information that the compiler already
  213     knows from parsing the code.</li>
  214     <li>It doesn't rely on embedded HTML, as such will impede
  215     extraction and formatting for other purposes.</li>
  216     <li>It's based on existing D comment forms, so it
  217     is completely independent of parsers only interested in D code.</li>
  218     <li>It should look and feel different from code, so it won't
  219     be visually confused with code.</li>
  220     <li>It should be possible for the user to use Doxygen or other
  221     documentation extractor if desired.</li>
  222 </ol>
  223 <div class="blankline"></div>
  224 <h2><a class="anchor" title="Permalink to this section" id="specifications" href="#specifications">Specification</a></h2>
  225 <div class="blankline"></div>
  226 <p>The specification for the form of embedded documentation comments only
  227 specifies how information is to be presented to the compiler.
  228 It is implementation-defined how that information is used and the form
  229 of the final presentation. Whether the final presentation form is an
  230 HTML web page, a man page, a PDF file, etc. is not specified as part of the
  231 D Programming Language.
  232 </p>
  233 <div class="blankline"></div>
  234 <h3><a class="anchor" title="Permalink to this section" id="phases_of_processing" href="#phases_of_processing">Phases of Processing</a></h3>
  235 <div class="blankline"></div>
  236 <p>Embedded documentation comments are processed in a series of phases:
  237 </p>
  238 <div class="blankline"></div>
  239 <ol>    <li>Lexical - documentation comments are identified and attached
  240     to tokens.</li>
  241     <li>Parsing - documentation comments are associated with
  242     specific declarations and combined.</li>
  243     <li>Sections - each documentation comment is divided up into
  244     a sequence of sections.</li>
  245     <li>Special sections are processed.</li>
  246     <li>Highlighting of non-special sections is done.</li>
  247     <li>All sections for the module are combined.</li>
  248     <li>Macro and Escape text substitution is performed to produce the final result.</li>
  249 </ol>
  250 <div class="blankline"></div>
  251 <h3><a class="anchor" title="Permalink to this section" id="lexical" href="#lexical">Lexical</a></h3>
  252 <div class="blankline"></div>
  253 <p>Embedded documentation comments are one of the following forms:
  254 </p>
  255 <div class="blankline"></div>
  256 <ol>    <li><span class="d_comment">/** ... */</span> The two *'s after the opening /</li>
  257     <li><span class="d_comment">/++ ... +/</span> The two +'s after the opening /</li>
  258     <li><span class="d_comment">///</span> The three slashes</li>
  259 </ol>
  260 <div class="blankline"></div>
  261 <p>The following are all embedded documentation comments:</p>
  262 <div class="blankline"></div>
  263 <pre class="d_code notranslate"><span class="d_comment">/// This is a one line documentation comment.
  264 </span>
  265 <span class="d_comment">/** So is this. */</span>
  267 <span class="d_comment">/++ And this. +/</span>
  269 <span class="d_comment">/**
  270    This is a brief documentation comment.
  271  */</span>
  273 <span class="d_comment">/**
  274  * The leading * on this line is not part of the documentation comment.
  275  */</span>
  277 <span class="d_comment">/*********************************
  278    The extra *'s immediately following the /** are not
  279    part of the documentation comment.
  280  */</span>
  282 <span class="d_comment">/++
  283    This is a brief documentation comment.
  284  +/</span>
  286 <span class="d_comment">/++
  287  + The leading + on this line is not part of the documentation comment.
  288  +/</span>
  290 <span class="d_comment">/+++++++++++++++++++++++++++++++++
  291    The extra +'s immediately following the / ++ are not
  292    part of the documentation comment.
  293  +/</span>
  295 <span class="d_comment">/**************** Closing *'s are not part *****************/</span>
  296 </pre>
  297 <div class="blankline"></div>
  298 <p>The extra *'s and +'s on the comment opening, closing and left margin are
  299 ignored and are not part
  300 of the embedded documentation.
  301 Comments not following one of those forms are not documentation comments.
  302 </p>
  303 <div class="blankline"></div>
  304 <h3><a class="anchor" title="Permalink to this section" id="parsing" href="#parsing">Parsing</a></h3>
  305 <div class="blankline"></div>
  306 <p>Each documentation comment is associated with a declaration.
  307 If the documentation comment is on a line by itself or with only whitespace
  308 to the left, it refers to the next
  309 declaration.
  310 Multiple documentation comments applying to the same declaration
  311 are concatenated.
  312 Documentation comments not associated with a declaration are ignored.
  313 Documentation comments preceding the <i>ModuleDeclaration</i> apply to the
  314 entire module.
  315 If the documentation comment appears on the same line to the right of a
  316 declaration, it applies to that.
  317 </p>
  318 <div class="blankline"></div>
  319 <p>If a documentation comment for a declaration consists only of the
  320 identifier <span class="d_inlinecode donthyphenate notranslate">ditto</span>
  321 then the documentation comment for the previous declaration at the same
  322 declaration scope is applied to this declaration as well.
  323 </p>
  324 <div class="blankline"></div>
  325 <p>If there is no documentation comment for a declaration, that declaration
  326 may not appear in the output. To ensure it does appear in the output,
  327 put an empty declaration comment for it.
  328 </p>
  329 <div class="blankline"></div>
  330 <pre class="d_code notranslate"><span class="d_keyword">int</span> a;  <span class="d_comment">/// documentation for a; b has no documentation
  331 </span><span class="d_keyword">int</span> b;
  333 <span class="d_comment">/** documentation for c and d */</span>
  334 <span class="d_comment">/** more documentation for c and d */</span>
  335 <span class="d_keyword">int</span> c;
  336 <span class="d_comment">/** ditto */</span>
  337 <span class="d_keyword">int</span> d;
  339 <span class="d_comment">/** documentation for e and f */</span> <span class="d_keyword">int</span> e;
  340 <span class="d_keyword">int</span> f;  <span class="d_comment">/// ditto
  341 </span>
  342 <span class="d_comment">/** documentation for g */</span>
  343 <span class="d_keyword">int</span> g; <span class="d_comment">/// more documentation for g
  344 </span>
  345 <span class="d_comment">/// documentation for C and D
  346 </span><span class="d_keyword">class</span> C
  347 {
  348     <span class="d_keyword">int</span> x; <span class="d_comment">/// documentation for C.x
  349 </span>
  350     <span class="d_comment">/** documentation for C.y and C.z */</span>
  351     <span class="d_keyword">int</span> y;
  352     <span class="d_keyword">int</span> z; <span class="d_comment">/// ditto
  353 </span>}
  355 <span class="d_comment">/// ditto
  356 </span><span class="d_keyword">class</span> D { }
  357 </pre>
  358 <div class="blankline"></div>
  359 <h3><a class="anchor" title="Permalink to this section" id="sections" href="#sections">Sections</a></h3>
  360 <div class="blankline"></div>
  361 <p>The document comment is a series of <i>Section</i>s.
  362 A <i>Section</i> is a name that is the first non-blank character on
  363 a line immediately followed by a ':'. This name forms the section name.
  364 The section name is not case sensitive.
  365 </p>
  366 <div class="blankline"></div>
  367 <p>Section names starting with 'http://' or 'https://' are not recognized as section names.
  368 </p>
  369 <div class="blankline"></div>
  370 <h4><a class="anchor" title="Permalink to this section" id="summary" href="#summary">Summary</a></h4>
  371 <div class="blankline"></div>
  372 <p>The first section is the <i>Summary</i>, and does not have a section name.
  373 It is first paragraph, up to a blank line or a section name.
  374 While the summary can be any length, try to keep it to one line.
  375 The <i>Summary</i> section is optional.
  376 </p>
  377 <div class="blankline"></div>
  378 <h4><a class="anchor" title="Permalink to this section" id="description" href="#description">Description</a></h4>
  379 <div class="blankline"></div>
  380 <p>The next unnamed section is the <i>Description</i>.
  381 It consists of all the paragraphs following the <i>Summary</i> until
  382 a section name is encountered or the end of the comment.
  383 </p>
  384 <div class="blankline"></div>
  385 <p>While the <i>Description</i> section is optional,
  386 there cannot be a <i>Description</i> without a <i>Summary</i> section.
  387 </p>
  388 <div class="blankline"></div>
  389 <pre class="d_code notranslate"><span class="d_comment">/***********************************
  390  * Brief summary of what
  391  * myfunc does, forming the summary section.
  392  *
  393  * First paragraph of synopsis description.
  394  *
  395  * Second paragraph of
  396  * synopsis description.
  397  */</span>
  399 <span class="d_keyword">void</span> myfunc() { }
  400 </pre>
  401 <div class="blankline"></div>
  402 <p>Named sections follow the <i>Summary</i> and <i>Description</i> unnamed sections.
  403 </p>
  404 <div class="blankline"></div>
  405 <h3><a class="anchor" title="Permalink to this section" id="standard_sections" href="#standard_sections">Standard Sections</a></h3>
  406 <div class="blankline"></div>
  407 <p>For consistency and predictability, there are several standard sections.
  408 None of these are required to be present.
  409 </p>
  410 <div class="blankline"></div>
  411 <dl><dt><b>Authors:</b></dt>
  412 <dd>Lists the author(s) of the declaration.</dd>
  413 <pre class="d_code notranslate"><span class="d_comment">/**
  414  * Authors: Melvin D. Nerd, melvin@mailinator.com
  415  */</span>
  416 </pre>
  417 <div class="blankline"></div>
  418 <dt> <b>Bugs:</b></dt>
  419 <dd>Lists any known bugs.</dd>
  420 <pre class="d_code notranslate"><span class="d_comment">/**
  421  * Bugs: Doesn't work for negative values.
  422  */</span>
  423 </pre>
  424 <div class="blankline"></div>
  425 <dt> <b>Date:</b></dt>
  426 <dd>Specifies the date of the current revision. The date should be in a form
  427      parseable by std.date.</dd>
  428 <div class="blankline"></div>
  429 <pre class="d_code notranslate"><span class="d_comment">/**
  430  * Date: March 14, 2003
  431  */</span>
  432 </pre>
  433 <div class="blankline"></div>
  434 <dt> <b>Deprecated:</b></dt>
  435 <dd>Provides an explanation for and corrective action to take if the associated
  436      declaration is marked as deprecated.</dd>
  437 <div class="blankline"></div>
  438 <pre class="d_code notranslate"><span class="d_comment">/**
  439  * Deprecated: superseded by function bar().
  440  */</span>
  442 <span class="d_keyword">deprecated</span> <span class="d_keyword">void</span> foo() { ... }
  443 </pre>
  444 <div class="blankline"></div>
  445 <dt> <b>Examples:</b></dt>
  446 <dd>Any usage examples</dd>
  447 <pre class="d_code notranslate"><span class="d_comment">/**
  448  * Examples:
  449  * --------------------
  450  * writeln("3"); // writes '3' to stdout
  451  * --------------------
  452  */</span>
  453 </pre>
  454 <div class="blankline"></div>
  455 <dt> <b>History:</b></dt>
  456 <dd>Revision history.</dd>
  457 <pre class="d_code notranslate"><span class="d_comment">/**
  458  * History:
  459  *      V1 is initial version
  460  *
  461  *      V2 added feature X
  462  */</span>
  463 </pre>
  464 <div class="blankline"></div>
  465 <dt> <b>License:</b></dt>
  466 <dd>Any license information for copyrighted code.</dd>
  467 <pre class="d_code notranslate"><span class="d_comment">/**
  468  * License: use freely for any purpose
  469  */</span>
  471 <span class="d_keyword">void</span> bar() { ... }
  472 </pre>
  473 <div class="blankline"></div>
  474 <dt> <b>Returns:</b></dt>
  475 <dd>Explains the return value of the function.
  476      If the function returns <b>void</b>, don't redundantly document it.</dd>
  477 <pre class="d_code notranslate"><span class="d_comment">/**
  478  * Read the file.
  479  * Returns: The contents of the file.
  480  */</span>
  482 <span class="d_keyword">void</span>[] readFile(<span class="d_keyword">const</span>(<span class="d_keyword">char</span>)[] filename) { ... }
  483 </pre>
  484 <div class="blankline"></div>
  485 <dt> <b>See_Also:</b></dt>
  486 <dd>List of other symbols and URLs to related items.</dd>
  487 <pre class="d_code notranslate"><span class="d_comment">/**
  488  * See_Also:
  489  *    foo, bar, http://www.digitalmars.com/d/phobos/index.html
  490  */</span>
  491 </pre>
  492 <div class="blankline"></div>
  493 <dt> <b>Standards:</b></dt>
  494 <dd>If this declaration is compliant with any particular standard,
  495 the description of it goes here.</dd>
  496 <pre class="d_code notranslate"><span class="d_comment">/**
  497  * Standards: Conforms to DSPEC-1234
  498  */</span>
  499 </pre>
  500 <div class="blankline"></div>
  501 <dt><b>Throws:</b></dt>
  502 <dd>Lists exceptions thrown and under what circumstances they are thrown.</dd>
  503 <pre class="d_code notranslate"><span class="d_comment">/**
  504  * Write the file.
  505  * Throws: WriteException on failure.
  506  */</span>
  508 <span class="d_keyword">void</span> writeFile(string filename) { ... }
  509 </pre>
  510 <div class="blankline"></div>
  511 <dt> <b>Version:</b></dt>
  512 <dd>Specifies the current version of the declaration.</dd>
  513 <pre class="d_code notranslate"><span class="d_comment">/**
  514  * Version: 1.6a
  515  */</span>
  516 </pre>
  517 </dl>
  518 <div class="blankline"></div>
  519 <h3><a class="anchor" title="Permalink to this section" id="special_sections" href="#special_sections">Special Sections</a></h3>
  520 <div class="blankline"></div>
  521 <p>Some sections have specialized meanings and syntax.
  522 </p>
  523 <div class="blankline"></div>
  524 <dl><dt> <b>Copyright:</b></dt>
  525 <dd>This contains the copyright notice. The macro COPYRIGHT is set to
  526      the contents of the section when it documents the module declaration.
  527      The copyright section only gets this special treatment when it
  528      is for the module declaration.</dd>
  529 <div class="blankline"></div>
  530 <pre class="d_code notranslate"><span class="d_comment">/** Copyright: Public Domain */</span>
  532 <span class="d_keyword">module</span> foo;
  533 </pre>
  534 <div class="blankline"></div>
  535 <dt> <b>Params:</b></dt>
  536 <dd>Function parameters can be documented by listing them in a params
  537      section. Each line that starts with an identifier followed by
  538      an '=' starts a new parameter description. A description can
  539      span multiple lines.</dd>
  540 <div class="blankline"></div>
  541 <pre class="d_code notranslate"><span class="d_comment">/***********************************
  542  * foo does this.
  543  * Params:
  544  *      x =     is for this
  545  *              and not for that
  546  *      y =     is for that
  547  */</span>
  549 <span class="d_keyword">void</span> foo(<span class="d_keyword">int</span> x, <span class="d_keyword">int</span> y)
  550 {
  551 }
  552 </pre>
  553 <div class="blankline"></div>
  554 <dt> <b>Macros:</b></dt>
  555 <dd>The macros section follows the same syntax as the <b>Params:</b> section.
  556      It's a series of <i>NAME</i>=<i>value</i> pairs.
  557      The <i>NAME</i> is the macro name, and <i>value</i> is the replacement
  558      text.</dd>
  559 <pre class="d_code notranslate"><span class="d_comment">/**
  560  * Macros:
  561  *      FOO =   now is the time for
  562  *              all good men
  563  *      BAR =   bar
  564  *      MAGENTA =   &lt;font color="magenta"&gt;&dollar;0&lt;/font&gt;
  565  */</span>
  566 </pre>
  567 <div class="blankline"></div>
  568 <div class="blankline"></div>
  569 <dt> <b>Escapes=</b></dt>
  570 <dd>The escapes section is a series of substitutions which replace special
  571      characters with a string. It's useful when the output format requires
  572      escaping of certain characters, for example in HTML <b>&amp;</b> should be
  573      escaped with <b>&amp;amp;</b>.</dd>
  574 <dd>The syntax is <b>/c/string/</b>, where <b>c</b>
  575      is either a single character, or multiple characters separated by
  576      whitespace or commas, and <b>string</b> is the replacement text.</dd>
  577 <div class="blankline"></div>
  578 <pre class="d_code notranslate"><span class="d_comment">/**
  579  * ESCAPES = /&amp;/AddressOf!/
  580  *           /!/Exclamation/
  581  *           /?/QuestionMark/
  582  *           /,/Comma/
  583  *           /{ }/Parens/
  584  *           /&lt;,&gt;/Arrows/
  585  */</span>
  586 </pre>
  587 </dl>
  588 <div class="blankline"></div>
  589 <h2><a class="anchor" title="Permalink to this section" id="highlighting" href="#highlighting">Highlighting</a></h2>
  590 <div class="blankline"></div>
  591 <h3><a class="anchor" title="Permalink to this section" id="embedded_comments" href="#embedded_comments">Embedded Comments</a></h3>
  592 <div class="blankline"></div>
  593 <p>    The documentation comments can themselves be commented using
  594     the &dollar;<span class="d_inlinecode donthyphenate notranslate">(DDOC_COMMENT comment text)</span> syntax. These comments do not
  595     nest.
  596 </p>
  597 <div class="blankline"></div>
  598 <h3><a class="anchor" title="Permalink to this section" id="embedded_code" href="#embedded_code">Embedded Code</a></h3>
  599 <div class="blankline"></div>
  600 <p>    D code can be embedded using lines beginning with at least three hyphens <span class="d_inlinecode donthyphenate notranslate">-</span>,
  601     backticks <span class="d_inlinecode donthyphenate notranslate">`</span> or tildes <span class="d_inlinecode donthyphenate notranslate">~</span> (ignoring whitespace) to
  602     delineate the code section:
  603 </p>
  604 <div class="blankline"></div>
  605 <pre class="d_code notranslate"><span class="d_comment">/++
  606  + Our function.
  607  +
  608  + Example:
  609  + ---
  610  + import std.stdio;
  611  +
  612  + void foo()
  613  + {
  614  +     writeln("foo!");  /* print the string */
  615  + }
  616  + ---
  617  +/</span>
  618 </pre>
  619 <div class="blankline"></div>
  620 <p>    Note that in the above example the documentation comment uses the
  621     <span class="d_comment">/++ ... +/</span> form so that <span class="d_comment">/* ... */</span> can be used
  622     inside the code section.
  623 </p>
  624 <div class="blankline"></div>
  625 <p>    D code gets automatic syntax highlighting. To include code in another
  626     language without syntax highlighting, add a language string at the end of
  627     the top delimiter line:
  628 </p>
  629 <div class="blankline"></div>
  630 <pre class="d_code notranslate"><span class="d_comment">/++
  631  + Some C++
  632  + ``` cpp
  633  + #include &lt;iostream&gt;
  634  +
  635  + void foo()
  636  + {
  637  +     std::cout &lt;&lt; "foo!";
  638  + }
  639  + ```
  640  +/</span>
  641 </pre>
  642 <div class="blankline"></div>
  643 <h3><a class="anchor" title="Permalink to this section" id="inline_code" href="#inline_code">Inline Code</a></h3>
  644 <div class="blankline"></div>
  645 <p>    Inline code can be written between backtick characters (`), similarly
  646     to the syntax used on GitHub, Reddit, Stack Overflow, and other websites. Both
  647     the opening and closing ` character must appear on the same line to trigger this
  648     behavior.
  649 </p>
  650 <div class="blankline"></div>
  651 <p>    Text inside these sections will be escaped according to the rules described above,
  652     then wrapped in a <span class="d_inlinecode donthyphenate notranslate">&dollar;(DDOC_BACKQUOTED)</span> macro. By default, this macro expands
  653     to be displayed as an inline text span, formatted as code.
  654 </p>
  655 <div class="blankline"></div>
  656 <p>    A literal backtick character can be output either as a non-paired ` on a single
  657     line or by using the <span class="d_inlinecode donthyphenate notranslate">&dollar;(BACKTICK)</span> macro.
  658 </p>
  659 <div class="blankline"></div>
  660 <pre class="d_code notranslate"> <span class="d_comment">/// Returns `true` if `a == b`.
  661 </span> <span class="d_keyword">void</span> foo() {}
  663  <span class="d_comment">/// Backquoted `&lt;html&gt;` will be displayed to the user instead
  664 </span> <span class="d_comment">/// of passed through as embedded HTML (see below).
  665 </span> <span class="d_keyword">void</span> bar() {}
  666 </pre>
  667 <div class="blankline"></div>
  668 <h3><a class="anchor" title="Permalink to this section" id="embedded_html" href="#embedded_html">Embedded HTML</a></h3>
  669 <div class="blankline"></div>
  670 <p>HTML can be embedded into the documentation comments, and it will
  671 be passed through to the HTML output unchanged.
  672 However, since it is not necessarily true that HTML will be the desired
  673 output format of the embedded documentation comment extractor, it is
  674 best to avoid using it where practical.
  675 </p>
  676 <div class="blankline"></div>
  677 <pre class="d_code notranslate"><span class="d_comment">/**
  678  * Example of embedded HTML:
  679  *
  680  * &lt;ol&gt;
  681  *   &lt;li&gt;&lt;a href="http://www.digitalmars.com"&gt;Digital Mars&lt;/a&gt;&lt;/li&gt;
  682  *   &lt;li&gt;&lt;a href="http://www.classicempire.com"&gt;Empire&lt;/a&gt;&lt;/li&gt;
  683  * &lt;/ol&gt;
  684  */</span>
  685 </pre>
  686 <div class="blankline"></div>
  687 <h3><a class="anchor" title="Permalink to this section" id="headings" href="#headings">Headings</a></h3>
  688 <div class="blankline"></div>
  689 <p>A long documentation section can be subdivided by adding headings. A heading is
  690 a line of text that starts with one to six <span class="d_inlinecode donthyphenate notranslate">#</span> characters followed by whitespace
  691 and then the heading text. The number of <span class="d_inlinecode donthyphenate notranslate">#</span> characters determines the heading
  692 level. Headings may optionally end with any number of trailing <span class="d_inlinecode donthyphenate notranslate">#</span> characters.
  693 </p>
  694 <div class="blankline"></div>
  695 <pre class="d_code notranslate"><span class="d_comment">/**
  696  * # H1
  697  * ## H2
  698  * ### H3
  699  * #### H4 ###
  700  * ##### H5 ##
  701  * ###### H6 #
  702  */</span>
  703 </pre>
  704 <div class="blankline"></div>
  705 <h3><a class="anchor" title="Permalink to this section" id="links" href="#links">Links</a></h3>
  706 <div class="blankline"></div>
  707 <p>Documentation may link to other documentation or to a URL. There are four
  708 styles of links:
  709 </p>
  710 <div class="blankline"></div>
  711 <pre class="d_code notranslate"><span class="d_comment">/**
  712  * Some links:
  713  *
  714  * 1. A [reference link][ref] and bare reference links: [ref] or [Object]
  715  * 2. An [inline link](https://dlang.org)
  716  * 3. A bare URL: https://dlang.org
  717  * 4. An ![image](https://dlang.org/images/d3.png)
  718  *
  719  * [ref]: https://dlang.org "The D Language Website"
  720  */</span>
  721 </pre>
  722 <div class="blankline"></div>
  723 <h4><a class="anchor" title="Permalink to this section" id="reference_links" href="#reference_links">Reference Links</a></h4>
  724 <div class="blankline"></div>
  725 <p>Reference-style links enclose a reference label in square brackets. They may
  726 optionally be preceded by some link text, also enclosed in square brackets.
  727 </p>
  728 <div class="blankline"></div>
  729 <p>The reference label must match a reference defined elsewhere. This may be a D
  730 symbol in scope of the source code being documented, like <span class="d_inlinecode donthyphenate notranslate">[Object]</span> in the
  731 example above, or it may be an explicit reference that is defined in the same
  732 documentation comment, like <span class="d_inlinecode donthyphenate notranslate">[ref]</span> in the example above. In the example both
  733 instances of <span class="d_inlinecode donthyphenate notranslate">[ref]</span> in item <span class="d_inlinecode donthyphenate notranslate">1.</span> will be replaced with the URL and title text
  734 from the matching definition at the bottom of the example. The first link will
  735 read <span class="d_inlinecode donthyphenate notranslate">reference link</span> and the second will read <span class="d_inlinecode donthyphenate notranslate">ref</span>.
  736 </p>
  737 <div class="blankline"></div>
  738 <p>Reference definitions start with a label in square brackets, followed by a
  739 colon, a URL and an optional title wrapped in single or double quotes, or in
  740 parentheses. If a reference label would match both a D symbol and a reference
  741 definition then the reference definition is used.
  742 </p>
  743 <div class="blankline"></div>
  744 <p>The generated links to D symbols are relative if they have the same root package
  745 as the module being documented. If not, their URLs are preceded by a
  746 <span class="d_inlinecode donthyphenate notranslate">&dollar;(DDOC_ROOT_pkg)</span> macro, where <span class="d_inlinecode donthyphenate notranslate">pkg</span> is the root package of the symbol
  747 being linked to. Links to D symbols are generated with a <span class="d_inlinecode donthyphenate notranslate">&dollar;(DOC_EXTENSION)</span>
  748 macro after the module name. So the generated URL for <span class="d_inlinecode donthyphenate notranslate">[Object]</span> in the above
  749 example is as if you had written:
  750 </p>
  751 <div class="blankline"></div>
  752 <pre class="d_code notranslate">&dollar;(DOC_ROOT_object)object&dollar;(DOC_EXTENSION)#.Object
  753 </pre>
  754 <div class="blankline"></div>
  755 <p>You may define your own <span class="d_inlinecode donthyphenate notranslate">DOC_ROOT_</span> macros for any external packages you wish
  756 to link to using a <a href="#macros">Macros section</a>.
  757 </p>
  758 <div class="blankline"></div>
  759 <h4><a class="anchor" title="Permalink to this section" id="inline_links" href="#inline_links">Inline Links</a></h4>
  760 <div class="blankline"></div>
  761 <p>Inline-style links enclose link text in square brackets and the link URL in
  762 parentheses. Like reference links, the URL may optionally be followed by title
  763 text wrapped in single or double quotes, or in parentheses:
  764 </p>
  765 <div class="blankline"></div>
  766 <pre class="d_code notranslate"><span class="d_comment">/// [a link with title text](https://dlang.org 'Some title text')
  767 </span></pre>
  768 <div class="blankline"></div>
  769 <h4><a class="anchor" title="Permalink to this section" id="urls" href="#urls">Bare URLs</a></h4>
  770 <div class="blankline"></div>
  771 <p>Bare URLs are sequences of characters that start with <span class="d_inlinecode donthyphenate notranslate">http://</span> or <span class="d_inlinecode donthyphenate notranslate">https://</span>,
  772 continue with one or more characters from the set of letters, digits and
  773 <span class="d_inlinecode donthyphenate notranslate">-_?=%&amp;/+#~.</span>, and contain at least one period.
  774 URL recognition happens before all macro text substitution.
  775 The URL is wrapped in a <span class="d_inlinecode donthyphenate notranslate">&dollar;(DDOC_LINK_AUTODETECT)</span> macro and is otherwise
  776 left untouched.
  777 </p>
  778 <div class="blankline"></div>
  779 <h4><a class="anchor" title="Permalink to this section" id="images" href="#images">Images</a></h4>
  780 <div class="blankline"></div>
  781 <p>Images have the same form as reference or inline links, but add an exclamation
  782 point <span class="d_inlinecode donthyphenate notranslate">!</span> before the initial square bracket. What would be the link text in a
  783 normal link is used as the image's alt text.
  784 </p>
  785 <div class="blankline"></div>
  786 <h3><a class="anchor" title="Permalink to this section" id="lists" href="#lists">Lists</a></h3>
  787 <div class="blankline"></div>
  788 <p>Documentation may contain lists. Start an ordered list with a number followed by
  789 a period:
  790 </p>
  791 <div class="blankline"></div>
  792 <pre class="d_code notranslate"><span class="d_comment">/**
  793  * 1. First this
  794  * 2. Then this
  795  *    1. A sub-item
  796  */</span>
  797 </pre>
  798 <div class="blankline"></div>
  799 <p>Start an unordered list with a hyphen (<span class="d_inlinecode donthyphenate notranslate">-</span>), an asterisk (<span class="d_inlinecode donthyphenate notranslate">*</span>) or a plus (<span class="d_inlinecode donthyphenate notranslate">+</span>).
  800 Subsequent items in the same list must also start with the same symbol:
  801 </p>
  802 <div class="blankline"></div>
  803 <pre class="d_code notranslate"><span class="d_comment">/**
  804  * - A list
  805  * - With a second item
  806  *
  807  * + A different list
  808  *   - With a sub-item
  809  *
  810  * * A third list (note the double asterisks)
  811  */</span>
  812 </pre>
  813 <div class="blankline"></div>
  814 <p>Note the double asterisks in the example above. This is because the list is
  815 inside a documentation comment that is delimited with asterisks, so the initial
  816 asterisk is considered part of the documentation comment, not a list item. This
  817 is even true when other lines don't start with an asterisk:
  818 </p>
  819 <div class="blankline"></div>
  820 <pre class="d_code notranslate"><span class="d_comment">/**
  821  - A list
  822  * Not a list because the asterisk is part of the documentation comment
  823  */</span>
  825 <span class="d_comment">/++
  826  + + The caveat also applies to plus-delimited documentation comments
  827  +/</span>
  828 </pre>
  829 <div class="blankline"></div>
  830 <p>List items can include content like new paragraphs, headings, embedded code, or
  831 child list items. Simply indent the content to match the indent of the text
  832 after the list symbol:
  833 </p>
  834 <div class="blankline"></div>
  835 <pre class="d_code notranslate"><span class="d_comment">/**
  836  * - A parent list item
  837  *
  838  *   With a second paragraph
  839  *
  840  *   - A sub-item
  841  *     ---
  842  *     // A code example inside the sub-item
  843  *     ---
  844  */</span>
  845 </pre>
  846 <div class="blankline"></div>
  847 <h3><a class="anchor" title="Permalink to this section" id="tables" href="#tables">Tables</a></h3>
  848 <div class="blankline"></div>
  849 <p>Data may be placed into a table. Tables consist of a single header row, a
  850 delimiter row, and zero or more data rows. Cells in each row are separated by
  851 pipe (<span class="d_inlinecode donthyphenate notranslate">|</span>) characters. Initial and trailing <span class="d_inlinecode donthyphenate notranslate">|</span>'s are optional. The number of
  852 cells in the delimiter row must match the number of cells in the header row:
  853 </p>
  854 <div class="blankline"></div>
  855 <pre class="d_code notranslate"><span class="d_comment">/**
  856  *  | Item | Price |
  857  *  | ---- | ----: |
  858  *  | Wigs | &dollar;10 |
  859  *    Wheels | &dollar;13
  860  *  | Widgets | &dollar;200 |
  861  */</span>
  862 </pre>
  863 <div class="blankline"></div>
  864 <p>Cells in the delimiter row contain hyphens (<span class="d_inlinecode donthyphenate notranslate">-</span>) and optional colons (<span class="d_inlinecode donthyphenate notranslate">:</span>).
  865 A <span class="d_inlinecode donthyphenate notranslate">:</span> to the left of the hyphens creates a left-aligned column, a <span class="d_inlinecode donthyphenate notranslate">:</span> to the
  866 right of the hyphens creates a right-aligned column (like the example above),
  867 and <span class="d_inlinecode donthyphenate notranslate">:</span>'s on both sides of the hyphens create a center-aligned column.
  868 </p>
  869 <div class="blankline"></div>
  870 <h3><a class="anchor" title="Permalink to this section" id="quotes" href="#quotes">Quotes</a></h3>
  871 <div class="blankline"></div>
  872 <p>Documentation may include a section of quoted material by prefixing each line of
  873 the section with a <span class="d_inlinecode donthyphenate notranslate">&gt;</span>. Quotes may include headings, lists, embedded code, etc.
  874 </p>
  875 <div class="blankline"></div>
  876 <pre class="d_code notranslate"><span class="d_comment">/**
  877  * &gt; To D, or not to D. -- Willeam NerdSpeare
  878  */</span>
  879 </pre>
  880 <div class="blankline"></div>
  881 <p>Lines of text that directly follow a quoted line are considered part of the quote:
  882 </p>
  883 <div class="blankline"></div>
  884 <pre class="d_code notranslate"><span class="d_comment">/**
  885  * &gt; This line
  886  * and this line are both part of the quote
  887  *
  888  * This line is not part of the quote.
  889  */</span>
  890 </pre>
  891 <div class="blankline"></div>
  892 <h3><a class="anchor" title="Permalink to this section" id="hrules" href="#hrules">Horizontal Rules</a></h3>
  893 <div class="blankline"></div>
  894 <p>Create a horizontal rule by adding a line containing three or more asterisks,
  895 underscores or hyphens:
  896 </p>
  897 <div class="blankline"></div>
  898 <pre class="d_code notranslate"><span class="d_comment">/**
  899  * ***
  900  * ___
  901  */</span>
  902 </pre>
  903 <div class="blankline"></div>
  904 <p>As with <a href="#lists">lists</a>, note that the initial <span class="d_inlinecode donthyphenate notranslate">*</span> in the example above
  905 will be stripped because it is part of a documentation comment that is delimited
  906 with asterisks, so you need at least three subsequent asterisks.
  907 </p>
  908 <div class="blankline"></div>
  909 <p>To create a horizontal rule with hyphens, add spaces between the hyphens.
  910 Without the spaces they would be treated as the start or end of an <a href="#embedded_code">embedded code block</a>. Note that any horizontal rule may contain
  911 spaces:
  912 </p>
  913 <div class="blankline"></div>
  914 <pre class="d_code notranslate"><span class="d_comment">/**
  915  * - - -
  916  * _ _ _
  917  * * * *
  918  */</span>
  919 </pre>
  920 <div class="blankline"></div>
  921 <h3><a class="anchor" title="Permalink to this section" id="text_emphasis" href="#text_emphasis">Text Emphasis</a></h3>
  922 <div class="blankline"></div>
  923 <p>A span of text wrapped in asterisks (<span class="d_inlinecode donthyphenate notranslate">*</span>) is emphasized, and text wrapped in
  924 two asterisks (<span class="d_inlinecode donthyphenate notranslate">**</span>) is strongly emphasized:
  925 </p>
  926 <div class="blankline"></div>
  927 <p><span class="d_inlinecode donthyphenate notranslate">*single asterisks*</span> is rendered as <em>single asterisks</em>.
  928 </p>
  929 <div class="blankline"></div>
  930 <p><span class="d_inlinecode donthyphenate notranslate">**double asterisks**</span> is rendered as <strong>double asterisks</strong>.
  931 </p>
  932 <div class="blankline"></div>
  933 <p>You can insert a literal asterisk by <a href="#punctuation_escapes">backslash-escaping</a> it: <span class="d_inlinecode donthyphenate notranslate">\*</span> is rendered as *.
  934 </p>
  935 <div class="blankline"></div>
  936 <p>Unlike <a href="https://daringfireball.net/projects/markdown/syntax">Markdown</a>,
  937 underscores (<span class="d_inlinecode donthyphenate notranslate">_</span>) are not supported for emphasizing text because it
  938 would break snake_case names and underscore prefix processing in
  939 <a href="#emphasis">identifier emphasis</a>.
  940 </p>
  941 <div class="blankline"></div>
  942 <h3><a class="anchor" title="Permalink to this section" id="emphasis" href="#emphasis">Identifier Emphasis</a></h3>
  943 <div class="blankline"></div>
  944 <p>Identifiers in documentation comments that are function parameters or are
  945 names that are in scope at the associated declaration are emphasized in
  946 the output.
  947 This emphasis can take the form of italics, boldface, a hyperlink, etc.
  948 How it is emphasized depends on what it is <nobr>&#x200A;&mdash;&#x200A;</nobr> a function parameter, type,
  949 D keyword, etc.
  950 To prevent unintended emphasis of an identifier, it can be preceded by
  951 an underscore (_). The underscore will be stripped from the output.
  952 </p>
  953 <div class="blankline"></div>
  954 <h3><a class="anchor" title="Permalink to this section" id="character_entities" href="#character_entities">Character Entities</a></h3>
  955 <div class="blankline"></div>
  956 <p>    Some characters have special meaning
  957     to the documentation processor, to avoid confusion it can be best
  958     to replace them with their corresponding character entities:
  959 </p>
  960 <div class="blankline"></div>
  961     <center><table><caption>Characters and Entities</caption>    <tr><th class="donthyphenate"><b>Character</b></th><th class="donthyphenate"><b>Entity</b></th></tr>
  962     <tr><td><span class="d_inlinecode donthyphenate notranslate">&lt;</span></td><td>&amp;lt;</td></tr>
  963     <tr><td><span class="d_inlinecode donthyphenate notranslate">&gt;</span></td><td>&amp;gt;</td></tr>
  964     <tr><td><span class="d_inlinecode donthyphenate notranslate">&amp;</span></td><td>&amp;amp;</td></tr></table></center>
  965 <div class="blankline"></div>
  966 <p>    It is not necessary to do this inside a code section, or if the
  967     special character is not immediately followed by a # or a letter.
  968 </p>
  969 <div class="blankline"></div>
  970 <h3><a class="anchor" title="Permalink to this section" id="punctuation_escapes" href="#punctuation_escapes">Punctuation Escapes</a></h3>
  971 <div class="blankline"></div>
  972 <p>    You can escape any ASCII punctuation symbol with a backslash <span class="d_inlinecode donthyphenate notranslate">\</span>.
  973     Doing so outputs the original character without the backslash, except for
  974     the following characters which output predefined macros instead:
  975 </p>
  976 <div class="blankline"></div>
  977     <center><table><caption>Characters and Escape Macros</caption>    <tr><th class="donthyphenate"><b>Character</b></th><th class="donthyphenate"><b>Macro</b></th></tr>
  978     <tr><td><span class="d_inlinecode donthyphenate notranslate">(</span></td><td>&dollar;(LPAREN)</td></tr>
  979     <tr><td><span class="d_inlinecode donthyphenate notranslate">)</span></td><td>&dollar;(RPAREN)</td></tr>
  980     <tr><td><span class="d_inlinecode donthyphenate notranslate">,</span></td><td>&dollar;(COMMA)</td></tr>
  981     <tr><td><span class="d_inlinecode donthyphenate notranslate">&dollar;</span></td><td>&dollar;(DOLLAR)</td></tr></table></center>
  982 <div class="blankline"></div>
  983 <p>    To output a backslash, simply use two backslashes in a row: <span class="d_inlinecode donthyphenate notranslate">\\</span>.
  984     Note that backslashes inside embedded or inline code do <em>not</em> escape
  985     punctuation and are included in the output as-is. Backslashes before
  986     non-punctation are also included in the output as-is. For example,
  987     <span class="d_inlinecode donthyphenate notranslate">C:\dmd2\bin\dmd.exe</span> does not require escaping its embedded backslashes.
  988 </p>
  989 <div class="blankline"></div>
  990 <h3><a class="anchor" title="Permalink to this section" id="no_documentation" href="#no_documentation">No Documentation</a></h3>
  991 <div class="blankline"></div>
  992 <p>    No documentation is generated for the following constructs,
  993     even if they have a documentation comment:
  994 </p>
  995 <div class="blankline"></div>
  996     <ul>    <li>Invariants</li>
  997     <li>Postblits</li>
  998     <li>Destructors</li>
  999     <li>Static constructors and static destructors</li>
 1000     <li>Class info, type info, and module info</li>
 1001     </ul>
 1002 <div class="blankline"></div>
 1003 <h2><a class="anchor" title="Permalink to this section" id="macros" href="#macros">Macros</a></h2>
 1004 <div class="blankline"></div>
 1005 <p>    The documentation comment processor includes a simple macro
 1006     text preprocessor.
 1007     When a &dollar;(<i>NAME</i>) appears
 1008     in section text it is replaced with <i>NAME</i>s corresponding
 1009     replacement text.</p>
 1010 <div class="blankline"></div>
 1011     For example:
 1012 <pre class="d_code notranslate"><span class="d_comment">/**
 1013 Macros:
 1014  PARAM = &lt;u&gt;&dollar;1&lt;/u&gt;
 1015  MATH_DOCS = &lt;a href="https://dlang.org/phobos/std_math.html"&gt;Math Docs&lt;/a&gt;
 1016 */</span>
 1017 <span class="d_keyword">module</span> math;
 1019 <span class="d_comment">/**
 1020  * This function returns the sum of &dollar;(PARAM a) and &dollar;(PARAM b).
 1021  * See also the &dollar;(MATH_DOCS).
 1022  */</span>
 1023 <span class="d_keyword">int</span> sum(<span class="d_keyword">int</span> a, <span class="d_keyword">int</span> b) { <span class="d_keyword">return</span> a + b; }
 1024 </pre>
 1025 <div class="blankline"></div>
 1026 <p>    The above would generate the following output:</p>
 1027 <div class="blankline"></div>
 1028 <pre class="d_code notranslate">&lt;h1&gt;test&lt;/h1&gt;
 1029 &lt;dl&gt;&lt;dt&gt;&lt;big&gt;&lt;a name=<span class="d_string">"sum"</span>&gt;&lt;/a&gt;<span class="d_keyword">int</span> &lt;u&gt;sum&lt;/u&gt;(<span class="d_keyword">int</span> &lt;i&gt;a&lt;/i&gt;, <span class="d_keyword">int</span> &lt;i&gt;b&lt;/i&gt;);
 1030 &lt;/big&gt;&lt;/dt&gt;
 1031 &lt;dd&gt;This <span class="d_keyword">function</span> returns the &lt;u&gt;sum&lt;/u&gt; of &lt;u&gt;&lt;i&gt;a&lt;/i&gt;&lt;/u&gt; and &lt;u&gt;&lt;i&gt;b&lt;/i&gt;&lt;/u&gt;.
 1032  See also the &lt;a href=<span class="d_string">"https://dlang.org/phobos/std_math.html"</span>&gt;Math Docs&lt;/a&gt;.
 1033 &lt;/dd&gt;
 1034 &lt;/dl&gt;
 1035 </pre>
 1036 <div class="blankline"></div>
 1037 <p>    The replacement text is recursively scanned for more macros.
 1038     If a macro is recursively encountered, with no argument or with
 1039     the same argument text as the enclosing macro, it is replaced
 1040     with no text.
 1041     Macro invocations that cut across replacement text boundaries are
 1042     not expanded.
 1043     If the macro name is undefined, the replacement text has no characters
 1044     in it.
 1045     If a &dollar;(NAME) is desired to exist in the output without being
 1046     macro expanded, the &dollar; should be <a href="#punctuation_escapes">    backslash-escaped</a>: <span class="d_inlinecode donthyphenate notranslate">\$</span>.
 1047 </p>
 1048 <div class="blankline"></div>
 1049 <p>    Macros can have arguments. Any text from the end of the identifier
 1050     to the closing &lsquo;)&rsquo; is the &dollar;0 argument.
 1051     A &dollar;0 in the replacement text is
 1052     replaced with the argument text.
 1053     If there are commas in the argument text, &dollar;1 will represent the
 1054     argument text up to the first comma, &dollar;2 from the first comma to
 1055     the second comma, etc., up to &dollar;9.
 1056     &dollar;+ represents the text from the first comma to the closing &lsquo;)&rsquo;.
 1057     The argument text can contain nested parentheses, "" or '' strings,
 1058     <span class="d_inlinecode donthyphenate notranslate">&lt;</span><span class="d_inlinecode donthyphenate notranslate">!--</span> <span class="d_inlinecode donthyphenate notranslate">...</span> <span class="d_inlinecode donthyphenate notranslate">--</span><span class="d_inlinecode donthyphenate notranslate">&gt;</span> comments, or tags.
 1059     If stray, unnested parentheses are used, they can be
 1060     <a href="#punctuation_escapes">backslash-escaped</a>: <span class="d_inlinecode donthyphenate notranslate">\(</span> or <span class="d_inlinecode donthyphenate notranslate">\)</span>.
 1061 </p>
 1062 <div class="blankline"></div>
 1063 <p>    Macro definitions come from the following sources,
 1064     in the specified order:
 1065 </p>
 1066 <div class="blankline"></div>
 1067     <ol>    <li>Predefined macros.</li>
 1068     <li>Definitions from file specified by
 1069     <a href="../dmd-windows.html">sc.ini</a>'s
 1070     or <a href="../dmd-linux.html#dmd_conf">dmd.conf</a> DDOCFILE setting.</li>
 1071     <li>Definitions from *.ddoc files specified on the command line.</li>
 1072     <li>Runtime definitions generated by Ddoc.</li>
 1073     <li>Definitions from any Macros: sections.</li>
 1074     </ol>
 1075 <div class="blankline"></div>
 1076 <p>    Macro redefinitions replace previous definitions of the same name.
 1077     This means that the sequence of macro definitions from the various
 1078     sources forms a hierarchy.
 1079 </p>
 1080 <div class="blankline"></div>
 1081 <p>    Macro names beginning with "D_" and "DDOC_" are reserved.
 1082 </p>
 1083 <div class="blankline"></div>
 1084 <h3><a class="anchor" title="Permalink to this section" id="predefined_macros" href="#predefined_macros">Predefined Macros</a></h3>
 1085 <div class="blankline"></div>
 1086 <p>    A number of macros are predefined Ddoc, and represent the
 1087     minimal definitions needed by Ddoc to format and highlight
 1088     the presentation.
 1089     The definitions are for simple HTML.</p>
 1090 <div class="blankline"></div>
 1091 <p>The implementations of all predefined macros are implementation-defined. The
 1092 reference implementation's macro definitions can be found <a href="https://github.com/dlang/dmd/blob/master/res/default_ddoc_theme.ddoc">here</a>.</p>
 1093 <div class="blankline"></div>
 1094 <p>    Ddoc does not generate HTML code. It formats into the basic
 1095     formatting macros, which (in their predefined form)
 1096     are then expanded into HTML.
 1097     If output other than HTML is desired, then these macros
 1098     need to be redefined.
 1099 </p>
 1100 <div class="blankline"></div>
 1101     <center><table><caption>Predefined Formatting Macros</caption>    <tr><th class="donthyphenate"><b>Name</b></th><th class="donthyphenate"><b>Description</b></th></tr>     <tr><td><span class="d_inlinecode donthyphenate notranslate">B</span></td><td>boldface the argument</td></tr>
 1102     <tr><td><span class="d_inlinecode donthyphenate notranslate">I</span></td><td>italicize the argument</td></tr>
 1103     <tr><td><span class="d_inlinecode donthyphenate notranslate">U</span></td><td>underline the argument</td></tr>
 1104     <tr><td><span class="d_inlinecode donthyphenate notranslate">P</span></td><td>argument is a paragraph</td></tr>
 1105     <tr><td><span class="d_inlinecode donthyphenate notranslate">DL</span></td><td>argument is a definition list</td></tr>
 1106     <tr><td><span class="d_inlinecode donthyphenate notranslate">DT</span></td><td>argument is a definition in a definition list</td></tr>
 1107     <tr><td><span class="d_inlinecode donthyphenate notranslate">DD</span></td><td>argument is a description of a definition</td></tr>
 1108     <tr><td><span class="d_inlinecode donthyphenate notranslate">TABLE</span></td><td>argument is a table</td></tr>
 1109     <tr><td><span class="d_inlinecode donthyphenate notranslate">TR</span></td><td>argument is a row in a table</td></tr>
 1110     <tr><td><span class="d_inlinecode donthyphenate notranslate">TH</span></td><td>argument is a header entry in a row</td></tr>
 1111     <tr><td><span class="d_inlinecode donthyphenate notranslate">TD</span></td><td>argument is a data entry in a row</td></tr>
 1112     <tr><td><span class="d_inlinecode donthyphenate notranslate">OL</span></td><td>argument is an ordered list</td></tr>
 1113     <tr><td><span class="d_inlinecode donthyphenate notranslate">UL</span></td><td>argument is an unordered list</td></tr>
 1114     <tr><td><span class="d_inlinecode donthyphenate notranslate">LI</span></td><td>argument is an item in a list</td></tr>
 1115     <tr><td><span class="d_inlinecode donthyphenate notranslate">BIG</span></td><td>argument is one font size bigger</td></tr>
 1116     <tr><td><span class="d_inlinecode donthyphenate notranslate">SMALL</span></td><td>argument is one font size smaller</td></tr>
 1117     <tr><td><span class="d_inlinecode donthyphenate notranslate">BR</span></td><td>start new line</td></tr>
 1118     <tr><td><span class="d_inlinecode donthyphenate notranslate">LINK</span></td><td>generate clickable link on argument</td></tr>
 1119     <tr><td><span class="d_inlinecode donthyphenate notranslate">LINK2</span></td><td>generate clickable link, first arg is address</td></tr>
 1120     <tr><td><span class="d_inlinecode donthyphenate notranslate">RED</span></td><td>argument is set to be red</td></tr>
 1121     <tr><td><span class="d_inlinecode donthyphenate notranslate">BLUE</span></td><td>argument is set to be blue</td></tr>
 1122     <tr><td><span class="d_inlinecode donthyphenate notranslate">GREEN</span></td><td>argument is set to be green</td></tr>
 1123     <tr><td><span class="d_inlinecode donthyphenate notranslate">YELLOW</span></td><td>argument is set to be yellow</td></tr>
 1124     <tr><td><span class="d_inlinecode donthyphenate notranslate">BLACK</span></td><td>argument is set to be black</td></tr>
 1125     <tr><td><span class="d_inlinecode donthyphenate notranslate">WHITE</span></td><td>argument is set to be white</td></tr>
 1126     <tr><td><span class="d_inlinecode donthyphenate notranslate">D_CODE</span></td><td>argument is D code</td></tr>
 1127     <tr><td><span class="d_inlinecode donthyphenate notranslate">D_INLINECODE</span></td><td>argument is inline D code</td></tr>
 1128     <tr><td><span class="d_inlinecode donthyphenate notranslate">LF</span></td><td>Insert a line feed (newline)</td></tr>
 1129     <tr><td><span class="d_inlinecode donthyphenate notranslate">LPAREN</span></td><td>Insert a left parenthesis</td></tr>
 1130     <tr><td><span class="d_inlinecode donthyphenate notranslate">RPAREN</span></td><td>Insert a right parenthesis</td></tr>
 1131     <tr><td><span class="d_inlinecode donthyphenate notranslate">BACKTICK</span></td><td>Insert a backtick</td></tr>
 1132     <tr><td><span class="d_inlinecode donthyphenate notranslate">DOLLAR</span></td><td>Insert a dollar sign</td></tr>
 1133     <tr><td><span class="d_inlinecode donthyphenate notranslate">DDOC</span></td><td>overall template for output</td></tr>
 1134     </table></center>
 1135 <div class="blankline"></div>
 1136 <p>    <b>DDOC</b> is special in that it specifies the boilerplate into
 1137     which the entire generated text is inserted (represented by the
 1138     Ddoc generated macro <b>BODY</b>). For example, in order
 1139     to use a style sheet, <b>DDOC</b> would be redefined as:
 1140 </p>
 1141 <div class="blankline"></div>
 1142 <pre class="ddoccode notranslate">DDOC = &lt;!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
 1143         "http://www.w3.org/TR/html4/strict.dtd"&gt;
 1144     &lt;html&gt;&lt;head&gt;
 1145     &lt;META http-equiv="content-type" content="text/html; charset=utf-8"&gt;
 1146     &lt;title&gt;&dollar;(TITLE)&lt;/title&gt;
 1147     &lt;link rel="stylesheet" type="text/css" href="style.css"&gt;
 1148     &lt;/head&gt;&lt;body&gt;
 1149     &lt;h1&gt;&dollar;(TITLE)&lt;/h1&gt;
 1150     &dollar;(BODY)
 1151     &lt;/body&gt;&lt;/html&gt;
 1152 </pre>
 1153 <div class="blankline"></div>
 1154 <p>    Highlighting of D code is performed by the following macros:
 1155 </p>
 1156 <div class="blankline"></div>
 1157     <center><table><caption>D Code Formatting Macros</caption>    <tr><th class="donthyphenate"><b>Name</b></th><th class="donthyphenate"><b>Description</b></th></tr>     <tr><td><span class="d_inlinecode donthyphenate notranslate">D_COMMENT</span></td><td>Highlighting of comments</td></tr>
 1158     <tr><td><span class="d_inlinecode donthyphenate notranslate">D_STRING</span></td><td>Highlighting of string literals</td></tr>
 1159     <tr><td><span class="d_inlinecode donthyphenate notranslate">D_KEYWORD</span></td><td>Highlighting of D keywords</td></tr>
 1160     <tr><td><span class="d_inlinecode donthyphenate notranslate">D_PSYMBOL</span></td><td>Highlighting of current declaration name</td></tr>
 1161     <tr><td><span class="d_inlinecode donthyphenate notranslate">D_PARAM</span></td><td>Highlighting of current function declaration parameters</td></tr>
 1162     </table></center>
 1163 <div class="blankline"></div>
 1164 <p>    The highlighting macros start with <span class="d_inlinecode donthyphenate notranslate">DDOC_</span>.
 1165     They control the formatting of individual parts of the presentation.
 1166 </p>
 1167 <div class="blankline"></div>
 1168     <center><table><caption>Ddoc Section Formatting Macros</caption>    <tr><th class="donthyphenate"><b>Name</b></th><th class="donthyphenate"><b>Description</b></th></tr>     <tr><td><span class="d_inlinecode donthyphenate notranslate">DDOC_CONSTRAINT</span></td><td>Highlighting of a template constraint.</td></tr>
 1169     <tr><td><span class="d_inlinecode donthyphenate notranslate">DDOC_COMMENT</span></td><td>Inserts a comment in the output.</td></tr>
 1170     <tr><td><span class="d_inlinecode donthyphenate notranslate">DDOC_DECL</span></td><td>Highlighting of the declaration.</td></tr>
 1171     <tr><td><span class="d_inlinecode donthyphenate notranslate">DDOC_DECL_DD</span></td><td>Highlighting of the description of a declaration.</td></tr>
 1172     <tr><td><span class="d_inlinecode donthyphenate notranslate">DDOC_DITTO</span></td><td>Highlighting of ditto declarations.</td></tr>
 1173     <tr><td><span class="d_inlinecode donthyphenate notranslate">DDOC_SECTIONS</span></td><td>Highlighting of all the sections.</td></tr>
 1174     <tr><td><span class="d_inlinecode donthyphenate notranslate">DDOC_SUMMARY</span></td><td>Highlighting of the summary section.</td></tr>
 1175     <tr><td><span class="d_inlinecode donthyphenate notranslate">DDOC_DESCRIPTION</span></td><td>Highlighting of the description section.</td></tr>
 1176     <tr><td><span class="d_inlinecode donthyphenate notranslate">DDOC_AUTHORS</span></td><td>Highlighting of the authors section.</td></tr>
 1177     <tr><td><span class="d_inlinecode donthyphenate notranslate">DDOC_BUGS</span></td><td>Highlighting of the bugs section.</td></tr>
 1178     <tr><td><span class="d_inlinecode donthyphenate notranslate">DDOC_COPYRIGHT</span></td><td>Highlighting of the copyright section.</td></tr>
 1179     <tr><td><span class="d_inlinecode donthyphenate notranslate">DDOC_DATE</span></td><td>Highlighting of the date section.</td></tr>
 1180     <tr><td><span class="d_inlinecode donthyphenate notranslate">DDOC_DEPRECATED</span></td><td>Highlighting of the deprecated section.</td></tr>
 1181     <tr><td><span class="d_inlinecode donthyphenate notranslate">DEPRECATED</span></td><td>Wrapper for deprecated declarations.</td></tr>
 1182     <tr><td><span class="d_inlinecode donthyphenate notranslate">DDOC_EXAMPLES</span></td><td>Highlighting of the examples section.</td></tr>
 1183     <tr><td><span class="d_inlinecode donthyphenate notranslate">DDOC_HISTORY</span></td><td>Highlighting of the history section.</td></tr>
 1184     <tr><td><span class="d_inlinecode donthyphenate notranslate">DDOC_LICENSE</span></td><td>Highlighting of the license section.</td></tr>
 1185     <tr><td><span class="d_inlinecode donthyphenate notranslate">DDOC_OVERLOAD_SEPARATOR</span></td><td>Inserts a separator between overloads of a given name.</td></tr>
 1186     <tr><td><span class="d_inlinecode donthyphenate notranslate">DDOC_RETURNS</span></td><td>Highlighting of the returns section.</td></tr>
 1187     <tr><td><span class="d_inlinecode donthyphenate notranslate">DDOC_SEE_ALSO</span></td><td>Highlighting of the see-also section.</td></tr>
 1188     <tr><td><span class="d_inlinecode donthyphenate notranslate">DDOC_STANDARDS</span></td><td>Highlighting of the standards section.</td></tr>
 1189     <tr><td><span class="d_inlinecode donthyphenate notranslate">DDOC_THROWS</span></td><td>Highlighting of the throws section.</td></tr>
 1190     <tr><td><span class="d_inlinecode donthyphenate notranslate">DDOC_VERSION</span></td><td>Highlighting of the version section.</td></tr>
 1191     <tr><td><span class="d_inlinecode donthyphenate notranslate">DDOC_SECTION_H</span></td><td>Highlighting of the section name of a non-standard section.</td></tr>
 1192     <tr><td><span class="d_inlinecode donthyphenate notranslate">DDOC_SECTION</span></td><td>Highlighting of the contents of a non-standard section.</td></tr>
 1193     <tr><td><span class="d_inlinecode donthyphenate notranslate">DDOC_MEMBERS</span></td><td>Default highlighting of all the members of a class, struct, etc.</td></tr>
 1194     <tr><td><span class="d_inlinecode donthyphenate notranslate">DDOC_MODULE_MEMBERS</span></td><td>Highlighting of all the members of a module.</td></tr>
 1195     <tr><td><span class="d_inlinecode donthyphenate notranslate">DDOC_CLASS_MEMBERS</span></td><td>Highlighting of all the members of a class.</td></tr>
 1196     <tr><td><span class="d_inlinecode donthyphenate notranslate">DDOC_STRUCT_MEMBERS</span></td><td>Highlighting of all the members of a struct.</td></tr>
 1197     <tr><td><span class="d_inlinecode donthyphenate notranslate">DDOC_ENUM_MEMBERS</span></td><td>Highlighting of all the members of an enum.</td></tr>
 1198     <tr><td><span class="d_inlinecode donthyphenate notranslate">DDOC_TEMPLATE_PARAM</span></td><td>Highlighting of a template's individual parameters.</td></tr>
 1199     <tr><td><span class="d_inlinecode donthyphenate notranslate">DDOC_TEMPLATE_PARAM_LIST</span></td><td>Highlighting of a template's parameter list.</td></tr>
 1200     <tr><td><span class="d_inlinecode donthyphenate notranslate">DDOC_TEMPLATE_MEMBERS</span></td><td>Highlighting of all the members of a template.</td></tr>
 1201     <tr><td><span class="d_inlinecode donthyphenate notranslate">DDOC_ENUM_BASETYPE</span></td><td>Highlighting of the type an enum is based upon</td></tr>
 1202     <tr><td><span class="d_inlinecode donthyphenate notranslate">DDOC_PARAMS</span></td><td>Highlighting of a function parameter section.</td></tr>
 1203     <tr><td><span class="d_inlinecode donthyphenate notranslate">DDOC_PARAM_ROW</span></td><td>Highlighting of a name=value function parameter.</td></tr>
 1204     <tr><td><span class="d_inlinecode donthyphenate notranslate">DDOC_PARAM_ID</span></td><td>Highlighting of the parameter name.</td></tr>
 1205     <tr><td><span class="d_inlinecode donthyphenate notranslate">DDOC_PARAM_DESC</span></td><td>Highlighting of the parameter value.</td></tr>
 1206     <tr><td><span class="d_inlinecode donthyphenate notranslate">DDOC_BLANKLINE</span></td><td>Inserts a blank line.</td></tr>
 1207     <tr><td><span class="d_inlinecode donthyphenate notranslate">DDOC_ANCHOR</span></td><td>Expands to a named anchor used for hyperlinking to a
 1208         particular declaration section. Argument &dollar;1 expands to the qualified declaration name.</td></tr>
 1209     <tr><td><span class="d_inlinecode donthyphenate notranslate">DDOC_PSYMBOL</span></td><td>Highlighting of declaration name to which a particular section is referring.</td></tr>
 1210     <tr><td><span class="d_inlinecode donthyphenate notranslate">DDOC_PSUPER_SYMBOL</span></td><td>Highlighting of the base type of a class.</td></tr>
 1211     <tr><td><span class="d_inlinecode donthyphenate notranslate">DDOC_KEYWORD</span></td><td>Highlighting of D keywords.</td></tr>
 1212     <tr><td><span class="d_inlinecode donthyphenate notranslate">DDOC_PARAM</span></td><td>Highlighting of function parameters.</td></tr>
 1213     <tr><td><span class="d_inlinecode donthyphenate notranslate">DDOC_BACKQUOTED</span></td><td>Inserts inline code.</td></tr>
 1214     <tr><td><span class="d_inlinecode donthyphenate notranslate">DDOC_AUTO_PSYMBOL_SUPPRESS</span></td><td>Highlighting of auto-detected symbol that starts with underscore</td></tr>
 1215     <tr><td><span class="d_inlinecode donthyphenate notranslate">DDOC_AUTO_PSYMBOL</span></td><td>Highlighting of auto-detected symbol</td></tr>
 1216     <tr><td><span class="d_inlinecode donthyphenate notranslate">DDOC_AUTO_KEYWORD</span></td><td>Highlighting of auto-detected keywords</td></tr>
 1217     <tr><td><span class="d_inlinecode donthyphenate notranslate">DDOC_AUTO_PARAM</span></td><td>Highlighting of auto-detected parameters</td></tr>
 1218     </table></center>
 1219 <div class="blankline"></div>
 1220 <p>    For example, one could redefine <span class="d_inlinecode donthyphenate notranslate">DDOC_SUMMARY</span>:
 1221 </p>
 1222 <div class="blankline"></div>
 1223 <pre class="ddoccode notranslate">DDOC_SUMMARY = &dollar;(GREEN &dollar;0)
 1224 </pre>
 1225 <div class="blankline"></div>
 1226 <p>    And all the summary sections will now be green.
 1227 </p>
 1228 <div class="blankline"></div>
 1229 <h3><a class="anchor" title="Permalink to this section" id="macro_def_scini" href="#macro_def_scini">Macro Definitions from <span class="d_inlinecode donthyphenate notranslate">sc.ini</span>'s DDOCFILE</a></h3>
 1230 <div class="blankline"></div>
 1231 <p>    A text file of macro definitions can be created,
 1232     and specified in <span class="d_inlinecode donthyphenate notranslate">sc.ini</span>:
 1233 </p>
 1234 <div class="blankline"></div>
 1235 <pre class="ddoccode notranslate">DDOCFILE=myproject.ddoc
 1236 </pre>
 1237 <div class="blankline"></div>
 1238 <h3><a class="anchor" title="Permalink to this section" id="macro_def_ddoc_file" href="#macro_def_ddoc_file">Macro Definitions from .ddoc Files on the Command Line</a></h3>
 1239 <div class="blankline"></div>
 1240 <p>    File names on the DMD command line with the extension
 1241     .ddoc are text files that are read and processed in order.
 1242 </p>
 1243 <div class="blankline"></div>
 1244 <h3><a class="anchor" title="Permalink to this section" id="macro_def_ddocgenerated" href="#macro_def_ddocgenerated">Macro Definitions Generated by Ddoc</a></h3>
 1245 <div class="blankline"></div>
 1246     <center><table><caption>Generated Macro Definitions</caption>    <tr><th class="donthyphenate"><b>Macro Name</b></th><th class="donthyphenate"><b>Content</b></th></tr>     <tr><td>    <b>BODY</b></td><td>    Set to the generated document text.
 1247     </td></tr>
 1248     <tr><td>    <b>TITLE</b></td><td>    Set to the module name.
 1249     </td></tr>
 1250     <tr><td>    <b>DATETIME</b></td><td>    Set to the current date and time.
 1251     </td></tr>
 1252     <tr><td>    <b>YEAR</b></td><td>    Set to the current year.
 1253     </td></tr>
 1254     <tr><td>    <b>COPYRIGHT</b></td><td>    Set to the contents of any <b>Copyright:</b> section that is part
 1255     of the module comment.
 1256     </td></tr>
 1257     <tr><td>    <b>DOCFILENAME</b></td><td>    Set to the name of the generated output file.
 1258     </td></tr>
 1259     <tr><td>    <b>SRCFILENAME</b></td><td>    Set to the name of the source file the documentation is being
 1260     generated from.
 1261     </td></tr>
 1262     </table></center>
 1263 <div class="blankline"></div>
 1264 <h2><a class="anchor" title="Permalink to this section" id="using_ddoc_to_generate_examples" href="#using_ddoc_to_generate_examples">Using Ddoc to generate examples from unit tests</a></h2>
 1265 <div class="blankline"></div>
 1266 <p>    Ddoc can automatically generate usage examples for declarations
 1267     using unit tests. If a declaration is followed by a documented
 1268     unit test, the code from the test will be inserted into the
 1269     example section of the declaration. This avoids the frequent
 1270     problem of having outdated documentation for pieces of code.
 1271 </p>
 1272 <div class="blankline"></div>
 1273 <p>    To create a documented unit test just add three forward
 1274     slashes before the unittest block, like this:</p>
 1275 <div class="blankline"></div>
 1276 <pre class="d_code notranslate"><span class="d_comment">///
 1277 </span><span class="d_keyword">unittest</span>
 1278 {
 1279     ...
 1280 }
 1281 </pre>
 1282 <div class="blankline"></div>
 1283     <p>For more information please see the full section on
 1284     <a href="unittest.html#documented-unittests">documented unit tests</a>.
 1285 </p>
 1286 <div class="blankline"></div>
 1287 <h2><a class="anchor" title="Permalink to this section" id="using_ddoc_for_other_documentation" href="#using_ddoc_for_other_documentation">Using Ddoc for other Documentation</a></h2>
 1288 <div class="blankline"></div>
 1289 <p>    Ddoc is primarily designed for use in producing documentation
 1290     from embedded comments. It can also, however, be used for
 1291     processing other general documentation.
 1292     The reason for doing this would be to take advantage of the
 1293     macro capability of Ddoc and the D code syntax highlighting
 1294     capability.
 1295 </p>
 1296 <div class="blankline"></div>
 1297 <p>    If the .d source file starts with the string "Ddoc" then it
 1298     is treated as general purpose documentation, not as a D
 1299     code source file. From immediately after the "Ddoc" string
 1300     to the end of the file or any "Macros:" section forms
 1301     the document. No automatic highlighting is done to that text,
 1302     other than highlighting of D code embedded between lines
 1303     delineated with --- lines. Only macro processing is done.
 1304 </p>
 1305 <div class="blankline"></div>
 1306 <p>    Much of the D documentation itself is generated this way,
 1307     including this page.
 1308     Such documentation is marked at the bottom as being
 1309     generated by Ddoc.
 1310 </p>
 1311 <div class="blankline"></div>
 1312 <h2><a class="anchor" title="Permalink to this section" id="security" href="#security">Security considerations</a></h2>
 1313 <div class="blankline"></div>
 1314 <p>    Note that DDoc comments may embed raw HTML, including
 1315     &lt;script&gt; tags. Be careful when publishing or distributing
 1316     rendered DDoc HTML generated from untrusted sources, as this may
 1317     allow <a href="https://en.wikipedia.org/wiki/Cross-site_scripting">    cross-site scripting</a>.
 1318 </p>
 1319 <div class="blankline"></div>
 1320 <h2><a class="anchor" title="Permalink to this section" id="links_to_d_documentation_generators" href="#links_to_d_documentation_generators">Links to D documentation generators</a></h2>
 1321 <div class="blankline"></div>
 1322 <p>    A list of current D documentation generators which use Ddoc
 1323     can be found on our <a href="https://wiki.dlang.org/Open_Source_Projects#Documentation_Generators">wiki page</a>.
 1324 </p>
 1325 <div class="blankline"></div>
 1327 <div style="float: left"><i class="fa fa-angle-left" aria-hidden="true"></i> <a href="../spec/iasm.html">D x86 Inline Assembler</a></div>
 1328 <div style="float: right"><a href="../spec/interfaceToC.html">Interfacing to C</a> <i class="fa fa-angle-right" aria-hidden="true"></i></div>
 1329 <div style="clear:both"></div>
 1333         <div class="smallprint" id="copyright">Copyright &copy; 1999-2020 by the <a href="../foundation_overview.html">D Language Foundation</a> | Page generated by
 1334 <a href="../spec/ddoc.html">Ddoc</a> on Fri Nov 20 21:58:03 2020
 1335 </div>
 1336     </div>
 1337 </div>
 1339     <script type="text/javascript" src="https://ajax.googleapis.com/ajax/libs/jquery/1.7.2/jquery.min.js"></script>
 1340     <script type="text/javascript">window.jQuery || document.write('\x3Cscript src="../js/jquery-1.7.2.min.js">\x3C/script>');</script>
 1341     <script type="text/javascript" src="../js/dlang.js"></script>
 1343     <script type="text/javascript" src="../js/codemirror-compressed.js"></script>
 1344     <script type="text/javascript" src="../js/run.js"></script>
 1347 <script type="text/javascript" src="../js/listanchors.js"></script>
 1348 <script type="text/javascript">jQuery(document).ready(addVersionSelector);</script>
 1349 <link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/font-awesome/4.4.0/css/font-awesome.min.css">
 1350 </body>
 1351 </html>