$(DDOC $(DDOC_BLANKLINE ) $(DDOC_BLANKLINE ) $(SPEC_S Embedded Documentation, $(DDOC_BLANKLINE ) $(HEADERNAV_TOC $(HEADERNAV_SUBITEMS specifications, Specification, $(HEADERNAV_ITEM phases_of_processing, Phases of Processing) $(HEADERNAV_ITEM lexical, Lexical) $(HEADERNAV_ITEM parsing, Parsing) $(HEADERNAV_ITEM sections, Sections) $(HEADERNAV_ITEM standard_sections, Standard Sections) $(HEADERNAV_ITEM special_sections, Special Sections) ) $(HEADERNAV_SUBITEMS highlighting, Highlighting, $(HEADERNAV_ITEM embedded_comments, Embedded Comments) $(HEADERNAV_ITEM embedded_code, Embedded Code) $(HEADERNAV_ITEM inline_code, Inline Code) $(HEADERNAV_ITEM embedded_html, Embedded HTML) $(HEADERNAV_ITEM headings, Headings) $(HEADERNAV_ITEM links, Links) $(HEADERNAV_ITEM lists, Lists) $(HEADERNAV_ITEM tables, Tables) $(HEADERNAV_ITEM quotes, Quotes) $(HEADERNAV_ITEM hrules, Horizontal Rules) $(HEADERNAV_ITEM text_emphasis, Text Emphasis) $(HEADERNAV_ITEM emphasis, Identifier Emphasis) $(HEADERNAV_ITEM character_entities, Character Entities) $(HEADERNAV_ITEM punctuation_escapes, Punctuation Escapes) $(HEADERNAV_ITEM no_documentation, No Documentation) ) $(HEADERNAV_SUBITEMS macros, Macros, $(HEADERNAV_ITEM macro_arguments, Macro Arguments) $(HEADERNAV_ITEM macro_definitions, Macro Definitions) $(HEADERNAV_ITEM predefined_macros, Predefined Macros) $(HEADERNAV_ITEM macro_def_scini, Macro Definitions from sc.ini's DDOCFILE) $(HEADERNAV_ITEM macro_def_ddoc_file, Macro Definitions from .ddoc Files on the Command Line) $(HEADERNAV_ITEM macro_def_ddocgenerated, Macro Definitions Generated by Ddoc) ) $(HEADERNAV_ITEM using_ddoc_to_generate_examples, Using Ddoc to generate examples from unit tests) $(HEADERNAV_ITEM using_ddoc_for_other_documentation, Using Ddoc for other Documentation) $(HEADERNAV_ITEM security, Security considerations) $(HEADERNAV_ITEM links_to_d_documentation_generators, Links to D documentation generators) ) $(DDOC_BLANKLINE ) $(P The D programming language enables embedding both contracts and test code along side the actual code, which helps to keep them all consistent with each other. One thing lacking is the documentation, as ordinary comments are usually unsuitable for automated extraction and formatting into manual pages. Embedding the user documentation into the source code has important advantages, such as not having to write the documentation twice, and the likelihood of the documentation staying consistent with the code. ) $(DDOC_BLANKLINE ) $(P Some existing approaches to this are: ) $(DDOC_BLANKLINE ) $(UL $(LI $(LINK2 https://www.doxygen.nl/, Doxygen) which already has some support for D) $(LI Java's $(LINK2 https://docs.oracle.com/javase/7/docs/technotes/guides/javadoc/index.html, Javadoc), probably the most well-known) $(LI C$(HASH )'s $(LINK2 https://msdn.microsoft.com/en-us/library/b2s063f7.aspx, embedded XML)) $(LI Other $(LINK2 https://doc.rust-lang.org/rustdoc/what-is-rustdoc.html, documentation tools)) ) $(DDOC_BLANKLINE ) $(P D's goals for embedded documentation are: ) $(DDOC_BLANKLINE ) $(OL $(LI It looks good as embedded documentation, not just after it is extracted and processed.) $(LI It's easy and natural to write, i.e. minimal reliance on $(LT )tags$(GT ) and other clumsy forms one would never see in a finished document.) $(LI It does not repeat information that the compiler already knows from parsing the code.) $(LI It doesn't rely on embedded HTML, as such will impede extraction and formatting for other purposes.) $(LI It's based on existing D comment forms, so it is completely independent of parsers only interested in D code.) $(LI It should look and feel different from code, so it won't be visually confused with code.) $(LI It should be possible for the user to use Doxygen or other documentation extractor if desired.) ) $(DDOC_BLANKLINE )

$(LNAME2 specifications, Specification)

$(DDOC_BLANKLINE ) $(P The specification for the form of embedded documentation comments only specifies how information is to be presented to the compiler. It is implementation-defined how that information is used and the form of the final presentation. Whether the final presentation form is an HTML web page, a man page, a PDF file, etc. is not specified as part of the D Programming Language. ) $(DDOC_BLANKLINE )

$(LNAME2 phases_of_processing, Phases of Processing)

$(DDOC_BLANKLINE ) $(P Embedded documentation comments are processed in a series of phases: ) $(DDOC_BLANKLINE ) $(OL $(LI Lexical - documentation comments are identified and attached to tokens.) $(LI Parsing - documentation comments are associated with specific declarations and combined.) $(LI Sections - each documentation comment is divided up into a sequence of sections.) $(LI Special sections are processed.) $(LI Highlighting of non-special sections is done.) $(LI All sections for the module are combined.) $(LI Macro and Escape text substitution is performed to produce the final result.) ) $(DDOC_BLANKLINE )

$(LNAME2 lexical, Lexical)

$(DDOC_BLANKLINE ) $(P Embedded documentation comments are one of the following forms: ) $(DDOC_BLANKLINE ) $(OL $(LI $(D_COMMENT /** ... */) The two *'s after the opening /) $(LI $(D_COMMENT /++ ... +/) The two +'s after the opening /) $(LI $(D_COMMENT ///) The three slashes) ) $(DDOC_BLANKLINE ) $(P The following are all embedded documentation comments:) $(DDOC_BLANKLINE ) $(D_CODE $(D_COMMENT /// This is a one line documentation comment. ) $(D_COMMENT /** So is this. */) $(D_COMMENT /++ And this. +/) $(D_COMMENT /** This is a brief documentation comment. */) $(D_COMMENT /** * The leading * on this line is not part of the documentation comment. */) $(D_COMMENT /********************************* The extra *'s immediately following the /** are not part of the documentation comment. */) $(D_COMMENT /++ This is a brief documentation comment. +/) $(D_COMMENT /++ + The leading + on this line is not part of the documentation comment. +/) $(D_COMMENT /+++++++++++++++++++++++++++++++++ The extra +'s immediately following the / ++ are not part of the documentation comment. +/) $(D_COMMENT /**************** Closing *'s are not part *****************/) ) $(DDOC_BLANKLINE ) $(P The extra *'s and +'s on the comment opening, closing and left margin are ignored and are not part of the embedded documentation. Comments not following one of those forms are not documentation comments. ) $(DDOC_BLANKLINE )

$(LNAME2 parsing, Parsing)

$(DDOC_BLANKLINE ) $(P Each documentation comment is associated with a declaration. If the documentation comment is on a line by itself or with only whitespace to the left, it refers to the next declaration. Multiple documentation comments applying to the same declaration are concatenated. Documentation comments not associated with a declaration are ignored. Documentation comments preceding the $(I ModuleDeclaration) apply to the entire module. If the documentation comment appears on the same line to the right of a declaration, it applies to that. ) $(DDOC_BLANKLINE ) $(P If a documentation comment for a declaration consists only of the identifier $(D ditto) then the documentation comment for the previous declaration at the same declaration scope is applied to this declaration as well. ) $(DDOC_BLANKLINE ) $(P If there is no documentation comment for a declaration, that declaration may not appear in the output. To ensure it does appear in the output, put an empty declaration comment for it. ) $(DDOC_BLANKLINE ) $(D_CODE $(D_KEYWORD int) a; $(D_COMMENT /// documentation for a; b has no documentation )$(D_KEYWORD int) b; $(D_COMMENT /** documentation for c and d */) $(D_COMMENT /** more documentation for c and d */) $(D_KEYWORD int) c; $(D_COMMENT /** ditto */) $(D_KEYWORD int) d; $(D_COMMENT /** documentation for e and f */) $(D_KEYWORD int) e; $(D_KEYWORD int) f; $(D_COMMENT /// ditto ) $(D_COMMENT /** documentation for g */) $(D_KEYWORD int) g; $(D_COMMENT /// more documentation for g ) $(D_COMMENT /// documentation for C and D )$(D_KEYWORD class) C { $(D_KEYWORD int) x; $(D_COMMENT /// documentation for C.x ) $(D_COMMENT /** documentation for C.y and C.z */) $(D_KEYWORD int) y; $(D_KEYWORD int) z; $(D_COMMENT /// ditto )} $(D_COMMENT /// ditto )$(D_KEYWORD class) D { } ) $(DDOC_BLANKLINE )

$(LNAME2 sections, Sections)

$(DDOC_BLANKLINE ) $(P The document comment is a series of $(I Section)s. A $(I Section) is a name that is the first non-blank character on a line immediately followed by a ':'. This name forms the section name. The section name is not case-sensitive. ) $(DDOC_BLANKLINE ) $(P Section names starting with 'http://' or 'https://' are not recognized as section names. ) $(DDOC_BLANKLINE )

$(LNAME2 summary, Summary)

$(DDOC_BLANKLINE ) $(P The first section is the $(I Summary), and does not have a section name. It is first paragraph, up to a blank line or a section name. While the summary can be any length, try to keep it to one line. The $(I Summary) section is optional. ) $(DDOC_BLANKLINE )

$(LNAME2 description, Description)

$(DDOC_BLANKLINE ) $(P The next unnamed section is the $(I Description). It consists of all the paragraphs following the $(I Summary) until a section name is encountered or the end of the comment. ) $(DDOC_BLANKLINE ) $(P While the $(I Description) section is optional, there cannot be a $(I Description) without a $(I Summary) section. ) $(DDOC_BLANKLINE ) $(D_CODE $(D_COMMENT /*********************************** * Brief summary of what * myfunc does, forming the summary section. * * First paragraph of synopsis description. * * Second paragraph of * synopsis description. */) $(D_KEYWORD void) myfunc() { } ) $(DDOC_BLANKLINE ) $(P Named sections follow the $(I Summary) and $(I Description) unnamed sections. ) $(DDOC_BLANKLINE )

$(LNAME2 standard_sections, Standard Sections)

$(DDOC_BLANKLINE ) $(P For consistency and predictability, there are several standard sections. None of these are required to be present. ) $(DDOC_BLANKLINE ) $(DL $(DT $(B Authors:)) $(DD Lists the author(s) of the declaration.) $(D_CODE $(D_COMMENT /** * Authors: Melvin D. Nerd, melvin@mailinator.com */) ) $(DDOC_BLANKLINE ) $(DT $(B Bugs:)) $(DD Lists any known bugs.) $(D_CODE $(D_COMMENT /** * Bugs: Doesn't work for negative values. */) ) $(DDOC_BLANKLINE ) $(DT $(B Date:)) $(DD Specifies the date of the current revision. The date should be in a form parseable by std.date.) $(DDOC_BLANKLINE ) $(D_CODE $(D_COMMENT /** * Date: March 14, 2003 */) ) $(DDOC_BLANKLINE ) $(DT $(B Deprecated:)) $(DD Provides an explanation for and corrective action to take if the associated declaration is marked as deprecated.) $(DDOC_BLANKLINE ) $(D_CODE $(D_COMMENT /** * Deprecated: superseded by function bar$(LPAREN)$(RPAREN ). */) $(D_KEYWORD deprecated) $(D_KEYWORD void) foo() { ... } ) $(DDOC_BLANKLINE ) $(DT $(B Examples:)) $(DD Any usage examples) $(D_CODE $(D_COMMENT /** * Examples: * -------------------- * writeln$(LPAREN)"3"$(RPAREN ); // writes '3' to stdout * -------------------- */) ) $(DDOC_BLANKLINE ) $(DT $(B History:)) $(DD Revision history.) $(D_CODE $(D_COMMENT /** * History: * V1 is initial version * * V2 added feature X */) ) $(DDOC_BLANKLINE ) $(DT $(B License:)) $(DD Any license information for copyrighted code.) $(D_CODE $(D_COMMENT /** * License: use freely for any purpose */) $(D_KEYWORD void) bar() { ... } ) $(DDOC_BLANKLINE ) $(DT $(B Returns:)) $(DD Explains the return value of the function. If the function returns $(B void), don't redundantly document it.) $(D_CODE $(D_COMMENT /** * Read the file. * Returns: The contents of the file. */) $(D_KEYWORD void)[] readFile($(D_KEYWORD const)($(D_KEYWORD char))[] filename) { ... } ) $(DDOC_BLANKLINE ) $(DT $(B See$(UNDERSCORE )Also:)) $(DD List of other symbols and URLs to related items.) $(D_CODE $(D_COMMENT /** * See_Also: * foo, bar, http://www.digitalmars.com/d/phobos/index.html */) ) $(DDOC_BLANKLINE ) $(DT $(B Standards:)) $(DD If this declaration is compliant with any particular standard, the description of it goes here.) $(D_CODE $(D_COMMENT /** * Standards: Conforms to DSPEC-1234 */) ) $(DDOC_BLANKLINE ) $(DT $(B Throws:)) $(DD Lists exceptions thrown and under what circumstances they are thrown.) $(D_CODE $(D_COMMENT /** * Write the file. * Throws: WriteException on failure. */) $(D_KEYWORD void) writeFile(string filename) { ... } ) $(DDOC_BLANKLINE ) $(DT $(B Version:)) $(DD Specifies the current version of the declaration.) $(D_CODE $(D_COMMENT /** * Version: 1.6a */) ) ) $(DDOC_BLANKLINE )

$(LNAME2 special_sections, Special Sections)

$(DDOC_BLANKLINE ) $(P Some sections have specialized meanings and syntax. ) $(DDOC_BLANKLINE ) $(DL $(DT $(B Copyright:)) $(DD This contains the copyright notice. The macro COPYRIGHT is set to the contents of the section when it documents the module declaration. The copyright section only gets this special treatment when it is for the module declaration.) $(DDOC_BLANKLINE ) $(D_CODE $(D_COMMENT /** Copyright: Public Domain */) $(D_KEYWORD module) foo; ) $(DDOC_BLANKLINE ) $(DT $(B Params:)) $(DD Function parameters can be documented by listing them in a params section. Each line that starts with an identifier followed by an '=' starts a new parameter description. A description can span multiple lines.) $(DDOC_BLANKLINE ) $(D_CODE $(D_COMMENT /*********************************** * foo does this. * Params: * x = is for this * and not for that * y = is for that */) $(D_KEYWORD void) foo($(D_KEYWORD int) x, $(D_KEYWORD int) y) { } ) $(DDOC_BLANKLINE ) $(DT $(B Macros:)) $(DD The macros section follows the same syntax as the $(B Params:) section. It's a series of $(I NAME)=$(I value) pairs. The $(I NAME) is the macro name, and $(I value) is the replacement text.) $(D_CODE $(D_COMMENT /** * Macros: * FOO = now is the time for * all good men * BAR = bar * MAGENTA = <font color="magenta">$0</font> */) ) ) $(DDOC_BLANKLINE ) $(DDOC_BLANKLINE )

$(LNAME2 highlighting, Highlighting)

$(DDOC_BLANKLINE )

$(LNAME2 embedded_comments, Embedded Comments)

$(DDOC_BLANKLINE ) $(P The documentation comments can themselves be commented using the $$(D (DDOC_COMMENT comment text)) syntax. These comments do not nest. ) $(DDOC_BLANKLINE )

$(LNAME2 embedded_code, Embedded Code)

$(DDOC_BLANKLINE ) $(P D code can be embedded using lines beginning with at least three hyphens -, backticks ` or tildes ~ (ignoring whitespace) to delineate the code section: ) $(DDOC_BLANKLINE ) $(D_CODE $(D_COMMENT /++ + Our function. + + Example: + --- + import std.stdio; + + void foo$(LPAREN)$(RPAREN ) + { + writeln$(LPAREN)"foo!"$(RPAREN ); /* print the string */ + } + --- +/) ) $(DDOC_BLANKLINE ) $(P Note that in the above example the documentation comment uses the $(D_COMMENT /++ ... +/) form so that $(D_COMMENT /* ... */) can be used inside the code section. ) $(DDOC_BLANKLINE ) $(P D code gets automatic syntax highlighting. To include code in another language without syntax highlighting, add a language string at the end of the top delimiter line: ) $(DDOC_BLANKLINE ) $(D_CODE $(D_COMMENT /++ + Some C++ + ``` cpp + #include <iostream> + + void foo$(LPAREN)$(RPAREN ) + { + std::cout << "foo!"; + } + ``` +/) ) $(DDOC_BLANKLINE )

$(LNAME2 inline_code, Inline Code)

$(DDOC_BLANKLINE ) $(P Inline code can be written between backtick characters (`), similarly to the syntax used on GitHub, Reddit, Stack Overflow, and other websites. Both the opening and closing ` character must appear on the same line to trigger this behavior. Note that macros are still expanded inside backticks. See also $(RELATIVE_LINK2 punctuation_escapes, escaping). ) $(DDOC_BLANKLINE ) $(P Text inside these sections will be escaped according to the rules described above, then wrapped in a $(DDOC_BACKQUOTED) macro. By default, this macro expands to be displayed as an inline text span, formatted as code. ) $(DDOC_BLANKLINE ) $(P A literal backtick character can be output either as a non-paired ` on a single line or by using the $(BACKTICK) macro. ) $(DDOC_BLANKLINE ) $(D_CODE $(D_COMMENT /// Returns `true` if `a == b`. ) $(D_KEYWORD void) foo() {} $(D_COMMENT /// Backquoted `<html>` will be displayed to the user instead ) $(D_COMMENT /// of passed through as embedded HTML $(LPAREN)see below$(RPAREN ). ) $(D_KEYWORD void) bar() {} ) $(DDOC_BLANKLINE )

$(LNAME2 embedded_html, Embedded HTML)

$(DDOC_BLANKLINE ) $(P HTML can be embedded into the documentation comments, and it will be passed through to the HTML output unchanged. However, since it is not necessarily true that HTML will be the desired output format of the embedded documentation comment extractor, it is best to avoid using it where practical. ) $(DDOC_BLANKLINE ) $(D_CODE $(D_COMMENT /** * Example of embedded HTML: * * <ol> * <li><a href="http://www.digitalmars.com">Digital Mars</a></li> * <li><a href="http://www.classicempire.com">Empire</a></li> * </ol> */) ) $(DDOC_BLANKLINE )

$(LNAME2 headings, Headings)

$(DDOC_BLANKLINE ) $(P A long documentation section can be subdivided by adding headings. A heading is a line of text that starts with one to six # characters followed by whitespace and then the heading text. The number of # characters determines the heading level. Headings may optionally end with any number of trailing # characters. ) $(DDOC_BLANKLINE ) $(D_CODE $(D_COMMENT /** * # H1 * ## H2 * ### H3 * #### H4 ### * ##### H5 ## * ###### H6 # */) ) $(DDOC_BLANKLINE )

$(LNAME2 links, Links)

$(DDOC_BLANKLINE ) $(P Documentation may link to other documentation or to a URL. There are four styles of links: ) $(DDOC_BLANKLINE ) $(D_CODE $(D_COMMENT /** * Some links: * * 1. A [reference link][ref] and bare reference links: [ref] or [Object] * 2. An [inline link]$(LPAREN)https://dlang.org$(RPAREN ) * 3. A bare URL: https://dlang.org * 4. An ![image]$(LPAREN)https://dlang.org/images/d3.png$(RPAREN ) * * [ref]: https://dlang.org "The D Language Website" */) ) $(DDOC_BLANKLINE )

$(LNAME2 reference_links, Reference Links)

$(DDOC_BLANKLINE ) $(P Reference-style links enclose a reference label in square brackets. They may optionally be preceded by some link text, also enclosed in square brackets. ) $(DDOC_BLANKLINE ) $(P The reference label must match a reference defined elsewhere. This may be a D symbol in scope of the source code being documented, like [Object] in the example above, or it may be an explicit reference that is defined in the same documentation comment, like [ref] in the example above. In the example both instances of [ref] in item 1. will be replaced with the URL and title text from the matching definition at the bottom of the example. The first link will read reference link and the second will read ref. ) $(DDOC_BLANKLINE ) $(P Reference definitions start with a label in square brackets, followed by a colon, a URL and an optional title wrapped in single or double quotes, or in parentheses. If a reference label would match both a D symbol and a reference definition then the reference definition is used. ) $(DDOC_BLANKLINE ) $(P The generated links to D symbols are relative if they have the same root package as the module being documented. If not, their URLs are preceded by a $(DDOC_ROOT_pkg) macro, where pkg is the root package of the symbol being linked to. Links to D symbols are generated with a $(DOC_EXTENSION) macro after the module name. Then the generated URL for [Object] in the above example is as if it had been written: ) $(DDOC_BLANKLINE ) $(D_CODE $(DOC_ROOT_object)object$(DOC_EXTENSION)#.Object ) $(DDOC_BLANKLINE ) $(P DOC_ROOT_ macros can be defined for any external packages to link to using a $(LINK2 #macros, Macros section). ) $(DDOC_BLANKLINE )

$(LNAME2 inline_links, Inline Links)

$(DDOC_BLANKLINE ) $(P Inline-style links enclose link text in square brackets and the link URL in parentheses. Like reference links, the URL may optionally be followed by title text wrapped in single or double quotes, or in parentheses: ) $(DDOC_BLANKLINE ) $(D_CODE $(D_COMMENT /// [a link with title text]$(LPAREN)https://dlang.org 'Some title text'$(RPAREN ) )) $(DDOC_BLANKLINE )

$(LNAME2 urls, Bare URLs)

$(DDOC_BLANKLINE ) $(P Bare URLs are sequences of characters that start with http:// or https://, continue with one or more characters from the set of letters, digits and -_?=%&/+#~., and contain at least one period. URL recognition happens before all macro text substitution. The URL is wrapped in a $(DDOC_LINK_AUTODETECT) macro and is otherwise left untouched. ) $(DDOC_BLANKLINE )

$(LNAME2 images, Images)

$(DDOC_BLANKLINE ) $(P Images have the same form as reference or inline links, but add an exclamation point ! before the initial square bracket. What would be the link text in a normal link is used as the image's alt text. ) $(DDOC_BLANKLINE )

$(LNAME2 lists, Lists)

$(DDOC_BLANKLINE ) $(P Documentation may contain lists. Start an ordered list with a number followed by a period: ) $(DDOC_BLANKLINE ) $(D_CODE $(D_COMMENT /** * 1. First this * 2. Then this * 1. A sub-item */) ) $(DDOC_BLANKLINE ) $(P Start an unordered list with a hyphen (-), an asterisk (*) or a plus (+). Subsequent items in the same list must also start with the same symbol: ) $(DDOC_BLANKLINE ) $(D_CODE $(D_COMMENT /** * - A list * - With a second item * * + A different list * - With a sub-item * * * A third list $(LPAREN)note the double asterisks$(RPAREN ) */) ) $(DDOC_BLANKLINE ) $(P Note the double asterisks in the example above. This is because the list is inside a documentation comment that is delimited with asterisks, so the initial asterisk is considered part of the documentation comment, not a list item. This is even true when other lines don't start with an asterisk: ) $(DDOC_BLANKLINE ) $(D_CODE $(D_COMMENT /** - A list * Not a list because the asterisk is part of the documentation comment */) $(D_COMMENT /++ + + The caveat also applies to plus-delimited documentation comments +/) ) $(DDOC_BLANKLINE ) $(P List items can include content like new paragraphs, headings, embedded code, or child list items. Simply indent the content to match the indent of the text after the list symbol: ) $(DDOC_BLANKLINE ) $(D_CODE $(D_COMMENT /** * - A parent list item * * With a second paragraph * * - A sub-item * --- * // A code example inside the sub-item * --- */) ) $(DDOC_BLANKLINE )

$(LNAME2 tables, Tables)

$(DDOC_BLANKLINE ) $(P Data may be placed into a table. Tables consist of a single header row, a delimiter row, and zero or more data rows. Cells in each row are separated by pipe (|) characters. Initial and trailing |'s are optional. The number of cells in the delimiter row must match the number of cells in the header row: ) $(DDOC_BLANKLINE ) $(D_CODE $(D_COMMENT /** * | Item | Price | * | ---- | ----: | * | Wigs | $10 | * Wheels | $13 * | Widgets | $200 | */) ) $(DDOC_BLANKLINE ) $(P Cells in the delimiter row contain hyphens (-) and optional colons (:). A : to the left of the hyphens creates a left-aligned column, a : to the right of the hyphens creates a right-aligned column (like the example above), and :'s on both sides of the hyphens create a center-aligned column. ) $(DDOC_BLANKLINE )

$(LNAME2 quotes, Quotes)

$(DDOC_BLANKLINE ) $(P Documentation may include a section of quoted material by prefixing each line of the section with a >. Quotes may include headings, lists, embedded code, etc. ) $(DDOC_BLANKLINE ) $(D_CODE $(D_COMMENT /** * > To D, or not to D. -- Willeam NerdSpeare */) ) $(DDOC_BLANKLINE ) $(P Lines of text that directly follow a quoted line are considered part of the quote: ) $(DDOC_BLANKLINE ) $(D_CODE $(D_COMMENT /** * > This line * and this line are both part of the quote * * This line is not part of the quote. */) ) $(DDOC_BLANKLINE )

$(LNAME2 hrules, Horizontal Rules)

$(DDOC_BLANKLINE ) $(P Create a horizontal rule by adding a line containing three or more asterisks, underscores or hyphens: ) $(DDOC_BLANKLINE ) $(D_CODE $(D_COMMENT /** * *** * ___ */) ) $(DDOC_BLANKLINE ) $(P As with $(LINK2 #lists, lists), note that the initial * in the example above will be stripped because it is part of a documentation comment that is delimited with asterisks. At least three subsequent asterisks are needed. ) $(DDOC_BLANKLINE ) $(P To create a horizontal rule with hyphens, add spaces between the hyphens. Without the spaces they would be treated as the start or end of an $(LINK2 #embedded_code, embedded code block). Note that any horizontal rule may contain spaces: ) $(DDOC_BLANKLINE ) $(D_CODE $(D_COMMENT /** * - - - * _ _ _ * * * * */) ) $(DDOC_BLANKLINE )

$(LNAME2 text_emphasis, Text Emphasis)

$(DDOC_BLANKLINE ) $(P A span of text wrapped in asterisks (*) is emphasized, and text wrapped in two asterisks (**) is strongly emphasized: ) $(DDOC_BLANKLINE ) $(P *single asterisks* is rendered as single asterisks. ) $(DDOC_BLANKLINE ) $(P **double asterisks** is rendered as double asterisks. ) $(DDOC_BLANKLINE ) $(P Insert a literal asterisk by $(LINK2 #punctuation_escapes, backslash-escaping) it: \* is rendered as *. ) $(DDOC_BLANKLINE ) $(P Unlike $(LINK2 https://daringfireball.net/projects/markdown/syntax, Markdown), underscores ($(UNDERSCORE )) are not supported for emphasizing text because it would break snake$(UNDERSCORE )case names and underscore prefix processing in $(LINK2 #emphasis, identifier emphasis). ) $(DDOC_BLANKLINE )

$(LNAME2 emphasis, Identifier Emphasis)

$(DDOC_BLANKLINE ) $(P Identifiers in documentation comments that are function parameters or are names that are in scope at the associated declaration are emphasized in the output. This emphasis can take the form of italics, boldface, a hyperlink, etc. How it is emphasized depends on what it is $(MDASH ) a function parameter, type, D keyword, etc. To prevent unintended emphasis of an identifier, it can be preceded by an underscore ($(UNDERSCORE )). The underscore will be stripped from the output. ) $(DDOC_BLANKLINE )

$(LNAME2 character_entities, Character Entities)

$(DDOC_BLANKLINE ) $(P Some characters have special meaning to the documentation processor, to avoid confusion it can be best to replace them with their corresponding character entities: ) $(DDOC_BLANKLINE ) $(TABLE2 Characters and Entities, Character, Entity $(TROW $(D <), $(AMP )lt;) $(TROW $(D >), $(AMP )gt;) $(TROW $(CODE_AMP ), $(AMP )amp;)) $(DDOC_BLANKLINE ) $(P It is not necessary to do this inside a code section, or if the special character is not immediately followed by a $(HASH ) or a letter. ) $(DDOC_BLANKLINE )

$(LNAME2 punctuation_escapes, Punctuation Escapes)

$(DDOC_BLANKLINE ) $(P Escape any ASCII punctuation symbol with a backslash \. Doing so outputs the original character without the backslash, except for the following characters which output predefined macros instead: ) $(DDOC_BLANKLINE ) $(TABLE2 Characters and Escape Macros, Character, Macro $(TROW $(D $(LPAREN)), $(LPAREN)) $(TROW $(D $(RPAREN )), $(RPAREN)) $(TROW $(D ,), $(COMMA)) $(TROW $(D $), $(DOLLAR))) $(DDOC_BLANKLINE ) $(P To output a backslash, simply use two backslashes in a row: \\. Note that backslashes inside embedded or inline code do not escape punctuation and are included in the output as-is. Backslashes before non-punctation are also included in the output as-is. For example, C:\dmd2\bin\dmd.exe does not require escaping its embedded backslashes. ) $(DDOC_BLANKLINE )

$(LNAME2 no_documentation, No Documentation)

$(DDOC_BLANKLINE ) $(P No documentation is generated for the following constructs, even if they have a documentation comment: ) $(DDOC_BLANKLINE ) $(UL $(LI Invariants) $(LI Postblits) $(LI Destructors) $(LI Static constructors and static destructors) $(LI Class info, type info, and $(DDSUBLINK abi, ModuleInfo, module info)) ) $(DDOC_BLANKLINE )

$(LNAME2 macros, Macros)

$(DDOC_BLANKLINE ) $(P The documentation comment processor includes a simple macro text preprocessor. When $(D $)(NAME) appears in section text it is replaced with the corresponding NAME macro's replacement text. Macros can take arguments: $(D $)(NAME argument). ) $(DDOC_BLANKLINE ) For example: $(D_CODE $(D_COMMENT /** Macros: PARAM = <u>$1</u> MATH_DOCS = <a href="https://dlang.org/phobos/std_math.html">Math Docs</a> */) $(D_KEYWORD module) math; $(D_COMMENT /** * This function returns the sum of $$(LPAREN)PARAM a$(RPAREN ) and $$(LPAREN)PARAM b$(RPAREN ). * See also the $$(LPAREN)MATH_DOCS$(RPAREN ). */) $(D_KEYWORD int) sum($(D_KEYWORD int) a, $(D_KEYWORD int) b) { $(D_KEYWORD return) a + b; } ) $(DDOC_BLANKLINE ) $(P The above would generate output such as:) $(DDOC_BLANKLINE ) $(D_CODE <h1>math</h1> <dl><dt><big><a name=$(D_STRING "sum")></a>$(D_KEYWORD int) <u>sum</u>($(D_KEYWORD int) <i>a</i>, $(D_KEYWORD int) <i>b</i>); </big></dt> <dd>This $(D_KEYWORD function) returns the <u>sum</u> of <u><i>a</i></u> and <u><i>b</i></u>. See also the <a href=$(D_STRING "https://dlang.org/phobos/std_math.html")>Math Docs</a>. </dd> </dl> ) $(DDOC_BLANKLINE ) $(P The replacement text is recursively scanned for more macros. If found, they are expanded in turn. If a macro already expanded is recursively encountered, with no argument or with the same argument text as the enclosing macro, it is replaced with no text. ) $(UL $(LI Macro invocations that cut across replacement text boundaries are not expanded. ) $(LI If the macro name is undefined, the replacement text will be $(D $)(DDOC_UNDEFINED_MACRO(NAME)). This defaults to empty. ) $(LI If $(D $)(NAME) is required to exist in the output without being macro expanded, the $ can be $(RELATIVE_LINK2 punctuation_escapes, backslash-escaped): \$. ) ) $(DDOC_BLANKLINE )

$(LNAME2 macro_arguments, Macro Arguments)

$(DDOC_BLANKLINE ) $(P When invoking a macro, any text from the end of the identifier to the closing $(SINGLEQUOTE $(RPAREN )) is passed as arguments to the macro, and can be referred to using the $(D $)0 parameter inside the macro definition. A $(D $)0 in the replacement text is replaced with the text of each argument, separated by commas. ) $(P If there are commas in the argument text, this denotes multiple arguments. Inside a macro definition, $(D $)1 will represent the argument text up to the first comma, $(D $)2 from the first comma to the second comma, etc., up to $(D $)9. $(D $)+ represents the text from the first comma to the closing $(SINGLEQUOTE $(RPAREN )). ) $(UL $(LI The argument text can contain nested parentheses, "" or '' strings, $(D <)$(D !--) $(D ...) $(D --)$(D >) comments, or tags. ) $(LI If stray, unnested parentheses are used, they can be $(RELATIVE_LINK2 punctuation_escapes, backslash-escaped): \$(LPAREN) or \$(RPAREN ). ) $(LI Any literal commas not intended as an argument separator can be escaped when invoking a macro expecting separate arguments. Defining an ARGS=$(D $)0 macro can be useful to handle commas - these are equivalent: $(UL $(LI $(D $)$(LPAREN)FOO one, $(D $)(ARGS two, dwa, dos), three$(RPAREN )) $(LI $(D $)(FOO one, two\, dwa\, dos, three).) ) ) ) $(DDOC_BLANKLINE )

$(LNAME2 macro_definitions, Macro Definitions)

$(DDOC_BLANKLINE ) $(P Macro definitions come from the following sources, in the specified order: ) $(DDOC_BLANKLINE ) $(OL $(LI Predefined macros.) $(LI Definitions from file specified by $(DPLLINK dmd-windows.html, sc.ini)'s or $(DDSUBLINK dmd-linux, dmd_conf, dmd.conf) DDOCFILE setting.) $(LI Definitions from *.ddoc files specified on the command line.) $(LI Runtime definitions generated by Ddoc.) $(LI Definitions from any Macros: sections.) ) $(DDOC_BLANKLINE ) $(P Macro redefinitions replace previous definitions of the same name. This means that the sequence of macro definitions from the various sources forms a hierarchy. ) $(DDOC_BLANKLINE ) $(P Macro names beginning with "D$(UNDERSCORE )" and "DDOC$(UNDERSCORE )" are reserved. ) $(DDOC_BLANKLINE )

$(LNAME2 predefined_macros, Predefined Macros)

$(DDOC_BLANKLINE ) $(P A number of macros are predefined Ddoc, and represent the minimal definitions needed by Ddoc to format and highlight the presentation. The definitions are for simple HTML.) $(DDOC_BLANKLINE ) $(P The implementations of all predefined macros are implementation-defined. The reference implementation's macro definitions can be found $(HTTPS github.com/dlang/dmd/blob/master/compiler/src/dmd/res/default_ddoc_theme.ddoc, here).) $(DDOC_BLANKLINE ) $(P Ddoc does not generate HTML code. It formats into the basic formatting macros, which (in their predefined form) are then expanded into HTML. If output other than HTML is desired, then these macros need to be redefined. ) $(DDOC_BLANKLINE ) $(LONGTABLE_2COLS 0.7, Predefined Formatting Macros, Name, Description, $(TROW $(ARGS $(D B)), $(ARGS boldface the argument)) $(TROW $(ARGS $(D I)), $(ARGS italicize the argument)) $(TROW $(ARGS $(D U)), $(ARGS underline the argument)) $(TROW $(ARGS $(D P)), $(ARGS argument is a paragraph)) $(TROW $(ARGS $(D DL)), $(ARGS argument is a definition list)) $(TROW $(ARGS $(D DT)), $(ARGS argument is a definition in a definition list)) $(TROW $(ARGS $(D DD)), $(ARGS argument is a description of a definition)) $(TROW $(ARGS $(D TABLE)), $(ARGS argument is a table)) $(TROW $(ARGS $(D TR)), $(ARGS argument is a row in a table)) $(TROW $(ARGS $(D TH)), $(ARGS argument is a header entry in a row)) $(TROW $(ARGS $(D TD)), $(ARGS argument is a data entry in a row)) $(TROW $(ARGS $(D OL)), $(ARGS argument is an ordered list)) $(TROW $(ARGS $(D UL)), $(ARGS argument is an unordered list)) $(TROW $(ARGS $(D LI)), $(ARGS argument is an item in a list)) $(TROW $(ARGS $(D BIG)), $(ARGS argument is one font size bigger)) $(TROW $(ARGS $(D SMALL)), $(ARGS argument is one font size smaller)) $(TROW $(ARGS $(D BR)), $(ARGS start new line)) $(TROW $(ARGS $(D LINK)), $(ARGS generate clickable link on argument)) $(TROW $(ARGS $(D LINK2)), $(ARGS generate clickable link, first arg is address)) $(TROW $(ARGS $(D RED)), $(ARGS argument is set to be red)) $(TROW $(ARGS $(D BLUE)), $(ARGS argument is set to be blue)) $(TROW $(ARGS $(D GREEN)), $(ARGS argument is set to be green)) $(TROW $(ARGS $(D YELLOW)), $(ARGS argument is set to be yellow)) $(TROW $(ARGS $(D BLACK)), $(ARGS argument is set to be black)) $(TROW $(ARGS $(D WHITE)), $(ARGS argument is set to be white)) $(TROW $(ARGS $(D D_CODE)), $(ARGS argument is D code)) $(TROW $(ARGS $(D D_INLINECODE)), $(ARGS argument is inline D code)) $(TROW $(ARGS $(D LF)), $(ARGS Insert a line feed (newline))) $(TROW $(ARGS $(D LPAREN)), $(ARGS Insert a left parenthesis)) $(TROW $(ARGS $(D RPAREN)), $(ARGS Insert a right parenthesis)) $(TROW $(ARGS $(D BACKTICK)), $(ARGS Insert a backtick)) $(TROW $(ARGS $(D DOLLAR)), $(ARGS Insert a dollar sign)) $(TROW $(ARGS $(D DDOC)), $(ARGS overall template for output)) $(TROW $(ARGS $(D ESCAPES)), $(ARGS characters to substitute)) ) $(DDOC_BLANKLINE ) $(P $(D DDOC) is special in that it specifies the boilerplate into which the entire generated text is inserted (represented by the Ddoc generated macro $(D BODY)). For example, in order to use a style sheet, $(D DDOC) would be redefined as: ) $(DDOC_BLANKLINE ) $(DDOCCODE DDOC = $(LT )!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd"$(GT ) $(LT )html$(GT )$(LT )head$(GT ) $(LT )META http-equiv="content-type" content="text/html; charset=utf-8"$(GT ) $(LT )title$(GT )$(TITLE)$(LT )/title$(GT ) $(LT )link rel="stylesheet" type="text/css" href="style.css"$(GT ) $(LT )/head$(GT )$(LT )body$(GT ) $(LT )h1$(GT )$(TITLE)$(LT )/h1$(GT ) $(BODY) $(LT )/body$(GT )$(LT )/html$(GT ) ) $(DDOC_BLANKLINE ) $(P $(D ESCAPES) defines a series of substitutions which replace special characters with a string. It's useful when the output format requires escaping of certain characters, for example in HTML $(D $(AMP )) should be escaped with $(D $(AMP )amp;). The syntax is $(D /c/string/), where $(D c) is either a single character, or multiple characters separated by whitespace or commas, and $(D string) is the replacement text.) $(DDOC_BLANKLINE ) $(D_CODE ESCAPES = /&/AddressOf!/ /!/Exclamation/ /?/QuestionMark/ /,/Comma/ /{ }/Parens/ /<,>/Arrows/ ) $(DDOC_BLANKLINE ) $(P Highlighting of D code is performed by the following macros: ) $(DDOC_BLANKLINE ) $(LONGTABLE_2COLS 0.7, D Code Formatting Macros, Name, Description, $(TROW $(ARGS $(D D_COMMENT)), $(ARGS Highlighting of comments)) $(TROW $(ARGS $(D D_STRING)), $(ARGS Highlighting of string literals)) $(TROW $(ARGS $(D D_KEYWORD)), $(ARGS Highlighting of D keywords)) $(TROW $(ARGS $(D D_PSYMBOL)), $(ARGS Highlighting of current declaration name)) $(TROW $(ARGS $(D D_PARAM)), $(ARGS Highlighting of current function declaration parameters)) ) $(DDOC_BLANKLINE ) $(P The highlighting macros start with $(D DDOC_). They control the formatting of individual parts of the presentation. ) $(DDOC_BLANKLINE ) $(LONGTABLE_2COLS 0.55, Ddoc Section Formatting Macros, Name, Description, $(TROW $(ARGS $(D DDOC_CONSTRAINT)), $(ARGS Highlighting of a template constraint.)) $(TROW $(ARGS $(D DDOC_COMMENT)), $(ARGS Inserts a comment in the output.)) $(TROW $(ARGS $(D DDOC_DECL)), $(ARGS Highlighting of the declaration.)) $(TROW $(ARGS $(D DDOC_DECL_DD)), $(ARGS Highlighting of the description of a declaration.)) $(TROW $(ARGS $(D DDOC_DITTO)), $(ARGS Highlighting of ditto declarations.)) $(TROW $(ARGS $(D DDOC_SECTIONS)), $(ARGS Highlighting of all the sections.)) $(TROW $(ARGS $(D DDOC_SUMMARY)), $(ARGS Highlighting of the summary section.)) $(TROW $(ARGS $(D DDOC_DESCRIPTION)), $(ARGS Highlighting of the description section.)) $(TROW $(ARGS $(D DDOC_AUTHORS)), $(ARGS Highlighting of the authors section.)) $(TROW $(ARGS $(D DDOC_BUGS)), $(ARGS Highlighting of the bugs section.)) $(TROW $(ARGS $(D DDOC_COPYRIGHT)), $(ARGS Highlighting of the copyright section.)) $(TROW $(ARGS $(D DDOC_DATE)), $(ARGS Highlighting of the date section.)) $(TROW $(ARGS $(D DDOC_DEPRECATED)), $(ARGS Highlighting of the deprecated section.)) $(TROW $(ARGS $(D DEPRECATED)), $(ARGS Wrapper for deprecated declarations.)) $(TROW $(ARGS $(D DDOC_EXAMPLES)), $(ARGS Highlighting of the examples section.)) $(TROW $(ARGS $(D DDOC_HISTORY)), $(ARGS Highlighting of the history section.)) $(TROW $(ARGS $(D DDOC_LICENSE)), $(ARGS Highlighting of the license section.)) $(TROW $(ARGS $(D DDOC_OVERLOAD_SEPARATOR)), $(ARGS Inserts a separator between overloads of a given name.)) $(TROW $(ARGS $(D DDOC_RETURNS)), $(ARGS Highlighting of the returns section.)) $(TROW $(ARGS $(D DDOC_SEE_ALSO)), $(ARGS Highlighting of the see-also section.)) $(TROW $(ARGS $(D DDOC_STANDARDS)), $(ARGS Highlighting of the standards section.)) $(TROW $(ARGS $(D DDOC_THROWS)), $(ARGS Highlighting of the throws section.)) $(TROW $(ARGS $(D DDOC_VERSION)), $(ARGS Highlighting of the version section.)) $(TROW $(ARGS $(D DDOC_SECTION_H)), $(ARGS Highlighting of the section name of a non-standard section.)) $(TROW $(ARGS $(D DDOC_SECTION)), $(ARGS Highlighting of the contents of a non-standard section.)) $(TROW $(ARGS $(D DDOC_MEMBERS)), $(ARGS Default highlighting of all the members of a class, struct, etc.)) $(TROW $(ARGS $(D DDOC_MODULE_MEMBERS)), $(ARGS Highlighting of all the members of a module.)) $(TROW $(ARGS $(D DDOC_CLASS_MEMBERS)), $(ARGS Highlighting of all the members of a class.)) $(TROW $(ARGS $(D DDOC_STRUCT_MEMBERS)), $(ARGS Highlighting of all the members of a struct.)) $(TROW $(ARGS $(D DDOC_ENUM_MEMBERS)), $(ARGS Highlighting of all the members of an enum.)) $(TROW $(ARGS $(D DDOC_TEMPLATE_PARAM)), $(ARGS Highlighting of a template's individual parameters.)) $(TROW $(ARGS $(D DDOC_TEMPLATE_PARAM_LIST)), $(ARGS Highlighting of a template's parameter list.)) $(TROW $(ARGS $(D DDOC_TEMPLATE_MEMBERS)), $(ARGS Highlighting of all the members of a template.)) $(TROW $(ARGS $(D DDOC_ENUM_BASETYPE)), $(ARGS Highlighting of the type an enum is based upon)) $(TROW $(ARGS $(D DDOC_PARAMS)), $(ARGS Highlighting of a function parameter section.)) $(TROW $(ARGS $(D DDOC_PARAM_ROW)), $(ARGS Highlighting of a name=value function parameter.)) $(TROW $(ARGS $(D DDOC_PARAM_ID)), $(ARGS Highlighting of the parameter name.)) $(TROW $(ARGS $(D DDOC_PARAM_DESC)), $(ARGS Highlighting of the parameter value.)) $(TROW $(ARGS $(D DDOC_BLANKLINE)), $(ARGS Inserts a blank line.)) $(TROW $(ARGS $(D DDOC_ANCHOR)), $(ARGS Expands to a named anchor used for hyperlinking to a particular declaration section. Argument $1 expands to the qualified declaration name.)) $(TROW $(ARGS $(D DDOC_PSYMBOL)), $(ARGS Highlighting of declaration name to which a particular section is referring.)) $(TROW $(ARGS $(D DDOC_PSUPER_SYMBOL)), $(ARGS Highlighting of the base type of a class.)) $(TROW $(ARGS $(D DDOC_KEYWORD)), $(ARGS Highlighting of D keywords.)) $(TROW $(ARGS $(D DDOC_PARAM)), $(ARGS Highlighting of function parameters.)) $(TROW $(ARGS $(D DDOC_BACKQUOTED)), $(ARGS Inserts inline code.)) $(TROW $(ARGS $(D DDOC_AUTO_PSYMBOL_SUPPRESS)), $(ARGS Highlighting of auto-detected symbol that starts with underscore)) $(TROW $(ARGS $(D DDOC_AUTO_PSYMBOL)), $(ARGS Highlighting of auto-detected symbol)) $(TROW $(ARGS $(D DDOC_AUTO_KEYWORD)), $(ARGS Highlighting of auto-detected keywords)) $(TROW $(ARGS $(D DDOC_AUTO_PARAM)), $(ARGS Highlighting of auto-detected parameters)) ) $(DDOC_BLANKLINE ) $(P For example, one could redefine $(D DDOC_SUMMARY): ) $(DDOC_BLANKLINE ) $(DDOCCODE DDOC_SUMMARY = $(GREEN $0) ) $(DDOC_BLANKLINE ) $(P And all the summary sections will now be green. ) $(DDOC_BLANKLINE )

$(LNAME2 macro_def_scini, Macro Definitions from sc.ini's DDOCFILE)

$(DDOC_BLANKLINE ) $(P A text file of macro definitions can be created, and specified in $(D sc.ini): ) $(DDOC_BLANKLINE ) $(DDOCCODE DDOCFILE=myproject.ddoc ) $(DDOC_BLANKLINE )

$(LNAME2 macro_def_ddoc_file, Macro Definitions from .ddoc Files on the Command Line)

$(DDOC_BLANKLINE ) $(P File names on the DMD command line with the extension .ddoc are text files that are read and processed in order. ) $(DDOC_BLANKLINE )

$(LNAME2 macro_def_ddocgenerated, Macro Definitions Generated by Ddoc)

$(DDOC_BLANKLINE ) $(LONGTABLE_2COLS 0.6, Generated Macro Definitions, Macro Name, Content, $(TROW $(ARGS $(B BODY)), $(ARGS Set to the generated document text.) ) $(TROW $(ARGS $(B TITLE)), $(ARGS Set to the module name.) ) $(TROW $(ARGS $(B DATETIME)), $(ARGS Set to the current date and time.) ) $(TROW $(ARGS $(B YEAR)), $(ARGS Set to the current year.) ) $(TROW $(ARGS $(B COPYRIGHT)), $(ARGS Set to the contents of any $(B Copyright:) section that is part of the module comment.) ) $(TROW $(ARGS $(B DOCFILENAME)), $(ARGS Set to the name of the generated output file.) ) $(TROW $(ARGS $(B SRCFILENAME)), $(ARGS Set to the name of the source file the documentation is being generated from.) ) ) $(DDOC_BLANKLINE )

$(LNAME2 using_ddoc_to_generate_examples, Using Ddoc to generate examples from unit tests)

$(DDOC_BLANKLINE ) $(P Ddoc can automatically generate usage examples for declarations using unit tests. If a declaration is followed by a documented unit test, the code from the test will be inserted into the example section of the declaration. This avoids the frequent problem of having outdated documentation for pieces of code. ) $(DDOC_BLANKLINE ) $(P To create a documented unit test just add three forward slashes before the unittest block, like this:) $(DDOC_BLANKLINE ) $(D_CODE $(D_COMMENT /// )$(D_KEYWORD unittest) { ... } ) $(DDOC_BLANKLINE ) $(P For more information please see the full section on $(LINK2 unittest.html#documented-unittests, documented unit tests). ) $(DDOC_BLANKLINE )

$(LNAME2 using_ddoc_for_other_documentation, Using Ddoc for other Documentation)

$(DDOC_BLANKLINE ) $(P Ddoc is primarily designed for use in producing documentation from embedded comments. It can also, however, be used for processing other general documentation. The reason for doing this would be to take advantage of the macro capability of Ddoc and the D code syntax highlighting capability. ) $(DDOC_BLANKLINE ) $(P If the .d source file starts with the string "Ddoc" then it is treated as general purpose documentation, not as a D code source file. From immediately after the "Ddoc" string to the end of the file or any "Macros:" section forms the document. No automatic highlighting is done to that text, other than highlighting of D code embedded between lines delineated with --- lines. Only macro processing is done. ) $(DDOC_BLANKLINE ) $(P Much of the D documentation itself is generated this way, including this page. Such documentation is marked at the bottom as being generated by Ddoc. ) $(DDOC_BLANKLINE )

$(LNAME2 security, Security considerations)

$(DDOC_BLANKLINE ) $(P Note that DDoc comments may embed raw HTML, including $(LT )script$(GT ) tags. Be careful when publishing or distributing rendered DDoc HTML generated from untrusted sources, as this may allow $(LINK2 https://en.wikipedia.org/wiki/Cross-site_scripting, cross-site scripting). ) $(DDOC_BLANKLINE )

$(LNAME2 links_to_d_documentation_generators, Links to D documentation generators)

$(DDOC_BLANKLINE ) $(P A list of current D documentation generators which use Ddoc can be found on our $(LINK2 https://wiki.dlang.org/Open_Source_Projects#Documentation_Generators, wiki page). ) $(DDOC_BLANKLINE ) $(SPEC_SUBNAV_PREV_NEXT iasm, D x86 Inline Assembler, interfaceToC, Interfacing to C) ) )