· Overview · D for Win32 · Win32 DLLs in D · C .h to D Modules · FAQ · Style Guide · Example: wc · Future · D Change Log · Tech Tips · Glossary · Acknowledgements Tools · DMD D Compiler · GDC D Compiler · Linker · Profiler Community · News Digest · News · Forum · Announcements · Learn · D links Archives · digitalmars.D · digitalmars.D.dtl · digitalmars.D.announce · digitalmars.D.learn · digitalmars.D.bugs · D.gnu · Old D |
Embedded DocumentationThe 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.Some existing approaches to this are:
SpecificationNote: This is not implemented, it's just a proposal.Embedded documentation comments are one of the following forms:
/// This is a one line documentation comment. /** So is this. */ /++ And this. +/ /** This is a brief documentation comment. */ /** * The leading * on this line is not part of the documentation comment. */ /********************************* The extra *'s immediately following the /** are not part of the documentation comment. */ /++ This is a brief documentation comment. +/ /++ + The leading + on this line is not part of the documentation comment. +/ /+++++++++++++++++++++++++++++++++ The extra +'s immediately following the /++ are not part of the documentation comment. +/The extra *'s and +'s on the comment opening and left margin are ignored and are not part of the embedded documentation. Comments not following one of those forms are not documentation comments. 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 with no intervening declarations are concatenated. Documentation comments preceding the 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. A documentation comment before the ModuleDeclaration applies to the entire module. If a documentation comment for a declaration consists only of the identifier ditto then the documentation comment for the previous declaration at the same scope is applied to this declaration as well. int a; /// documentation for a; b has no documentation int b; /** documentation for c and d */ /** more documentation for c and d */ int c; /** ditto */ int d; /** documentation for e and f */ int e; int f; /// ditto /// documentation for C and D class C { int x; /// documentation for C.x /** documentation for C.y and C.z */ int y; int z; /// ditto } /// ditto class D { } Basic StructureThe first paragraph, up to a blank line or a Section, of a documentation comment forms the summary line. Summary lines should be short. Subsequent paragraphs form the more detailed description. Paragraphs are delineated by blank lines or Sections./*********************************** * Brief summary of what * myfunc does. * * First paragraph of fuller description. * * Second paragraph of * fuller description. */ void myfunc() { }Function parameters can be documented by associating a comment with each parameter: /*********************************** * foo does this. */ void foo( int x, /// is for this int y /// is for that ) { } HyperlinksHyperlinks and email addresses can just be inserted as is, the documentation extractor will convert them into HTML hyperlinks as necessary:/** For more information mail to foo@bar.com or look at the website http://www.bar.com. */ Embedded HTMLHTML 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./** Example of embedded HTML: * <ol> * <li> <a href="www.digitalmars.com">Digital Mars</a> * <li> <a href="www.classicempire.com">Empire</a> * </ol> */ EmphasisIdentifiers 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 - a function parameter, type, D keyword, etc. To prevent unintended emphasis of an identifier, it can be preceded by an underscore (_). The underscore will be stripped from the output.SectionsAdditional, more specific information can be delineated with Sections. Sections start with an identifier being the first non-whitespace on a line, immediately followed by a colon ":". They are optional and case-insensitive. The section continues until either the end of the documentation comment or another section. Unrecognized sections are passed through to the output unchanged.Author:Specifies the name of the author./** * Author: Melvin D. Nerd */ Code:Used for embedding example D code. Because D code can contain comments, the /++ ... +/ should probably be the documentation comment used for code sections./+++++++++++++++++++++++++ + Code: + int func() + { + return 3; /* the value */ + } +/ Date:Specifies the date of the last revision. The date should be in a form parseable by std.date./** * Date: March 14, 2003 */ Deprecated:Provides an explanation for and corrective action to take if the associated declaration is marked as deprecated./** * Deprecated: superseded by function bar(). */ deprecated void foo() { ... } Include:Specifies a file to be inserted verbatim into the output of the documentation processor. The file can contain additional documentation, or things like boilerplate./** * Include: boilerplate.txt */ License:Specifies the license.Keywords:Keywords are added to the list of identifiers to be emphasized. They only apply to the current documentation comments or to documentation comments nested within the scope of the associated declaration./** * This cow will be emphasized. * Keywords: fread, fwrite, cow */ class A { /** A, x and cow will be emphasized */ int x; } /** * This cow won't be emphasized. */ class B { } Params:This is an alternate method of documenting a function's parameters. The first identifier of each subsequent line is taken to be a parameter name, followed by its description. Multiple description lines are lined up with the start of the first description line./** This is my function. * Params: * fp File pointer * name File name and * more. */ void foo(FILE *fp, char[] name) { .. } Returns:Explains the return value of the function. If the function returns void, don't redundantly document it./** * Read the file. * Returns: The contents of the file. */ void[] readFile(char[] filename) { ... } URL:In order for hyperlinks to symbols outside of the current module, the documentation extractor must know the URL where they will be located. The URL section is a list of pairs of module names and URL prefixes.import std.string; /** * Thid identifier toupper will be replaced by a hyperlink to * http://www.digitalmars.com/d/phobos/std_string.html#toupper. * * URL: * std.string http://www.digitalmars.com/d/phobos/std_string.html */ Version:Specifies the version./** * Version: 1.6a */ |
Add feedback and comments regarding this page.