yidabu 2007-4-26 16:11
27 D语言 嵌入式文档 Embedded Documentation
27 D语言 嵌入式文档 Embedded Documentation知识若不分享 实在没有意义 http://www.d-programming-language-china.org 20070425点击下面网址查看原文:http://www.d-programming-language-china.org by: D语言论坛 http://www.d-programming-language-china.org from: http://www.digitalmars.com/d/ddoc.html version: 基于D 1.013 (Apr 19, 2007) 嵌入式文档 D语言能够嵌入契约和测试代码到实际的代码中，这样帮助所有的保持一致。一个缺乏的事情是文档。平常的注释不适合自动摘要和格式化到手册。嵌入文档到源代码有重大好处，不用写两次文档，文档也能和代码保持一致。 这有些存在的工具做这件事情： Doxygen which already has some support for D http://www.stack.nl/~dimitri/doxygen/ Java's Javadoc, probably the mol-known http://java.sun.com/j2se/javado/ C#'s embedded XML http://msdn.mirootco/ibrary/default.asp?url=/library/en-s/se/hm/vcoriXMLDocumentation.asp Other documentaio tools tt://www.python.org/sigs/doc-sig/otherlangs.html( 本文出处: http://www.d-programming-language-china.org ) D嵌入文档的目标： 1 嵌入式文档本身看起就是很好的文档 2 文档书写起来很自然，对于正式文档中从来看不到的各种标签和其他复杂格式的依赖很少 3 编译器可以从代码中解析出来的信息不再重复 4 不依赖嵌入的HTML，以免妨碍提取文档用于其他目的 5 基于现有D注释格格，完全不依赖解析器。解器仅仅对D代码感兴趣:＞ 6 外观上和代码区分开来，文档和代码并存不会造成视觉上的混乱 7 需要的话用户可以使用Doxygen或者其他文档提取工具生成独立文档 (D语言论坛 http://www.d-programming-language-china.org 注：第二点和yidabuTxt文本格式很像，yidabuTxt文本格式是yidabu花了几个月的时间设计，并实现自动格式化为html)Specification详细说明 嵌入注释文档的规格说明仅仅指定了信息如何提供给编译器。这是一个关于信息使用和最终呈现样式的实现定义，最终的表现样式可能是Html网页，主页，PDF文件等。这不是D程序语言的一部分 1 Phases of Processing处理过程 嵌入文档注释依照以下顺序处理： 1.1 Lexical词法 doumntaioncomments are identified and attached to tokens.( 本文出处: http://www.d-programming-language-china.org ) 1.2 Parsing 解析 documentation comments are associated with specific declarations and combined. 1.3 Sections 分节 each documentation comment is divided up into a sequence of sections. 1.4 Special sections are processed. 1.5 Highlighting of non-special sections is done 1.6 All sections for the module are combined. 1.7 Macro text substitution is performed to produce the final result. 2 Lexical 词法 嵌入文档注释有以下几种格式： [Copy to clipboard] [ - ]CODE: /** ... */ The two *'s after the opening / /++ ... +/ The two +'s after the opening / /// The three slashes 下面全部是嵌入文档注释： [Copy to clipboard] [ - ]CODE: /// 单行文档注释 /** 同样是. */ /+ 也是注释+/ /** 一条概要注释. */ /** * 行首的*不属于文档注释(d-programming-language-china.org注：如果正式文档中有许多*岂不是怪怪的）. */ /********************************* **后直接尾随添加的*不属于文档注释. */ /++ 一条概要注释. +/ /++ + 行首的+不属于文档注释属档. +/ /+++++++++++++++++++++++++++++++++ ++ 后直接尾随的+不属于文档注释(d-programming-language-china.org:岂不是想写多少个+就个+) +/ /**************** Closing *'s are not part ************* 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.( 本文出处: http://www.d-programming-language-china.org ) 2 Parsing解析 每条文档注释都和一条声明相关联。独占一行的文档注释或者在同行声明左边的， 关联到下条声明。 用到同一声明的多条文档注释被组合在一起。 没有关联声明的文档注释被忽略。 模块声明文档注释应用到整个模块 处在声明 同行文档注释应用到该条声明。 如果是标识符ditto,表示本条声明范围和先前那条声明范围相同。(d-programming-language-china.org注：ditto大概是do it to,好记很) 没有文档注释的声明可能不出现在文档的输出，要避免这种情况可以加条空文档注释。 [Copy to clipboard] [ - ]CODE: int a; /// a的文档，b没有文档 int b; /** c和d的文档 */ /** 更多c和d的文档 */ int c; /** ditto */ int d; /* e的文档 */ int e; int f; /// ditto /** g的文档 */ int g; ///更多g的文档 /// C和D文档 class C { int x; /// C.x的文档 /** C.y 和C.z的文档 */ int y; int z; /// ditto /// ditto class D { } 3 Sections节 文档注释由连续的节组成。每节由节名开始，节名是非空白字符后面紧跟':'。节名不区分大小写。 1.1 Summary摘要 第一节是摘要，没有节名。也就是第一段直到空行或一个节名。虽然摘要可以任意长度，不过你可以让它保持在一行内。摘要是可选的。 1.2 Descripti描述 第二节是描述。从摘要开始直到节名或者注释结束。 尽管描述是可选的，但存在描述的话必须存在摘要。 [Copy to clipboard] [ - ]CODE: /*********************************** * Brief summary of what * myfunc does, forming the summary section. * * First paragraph of synopsis description. * * Second paragraph of * synopsis description. */ void myfunc() { } Named sections follow the Summary and Description unnamed sections.( 本文出处: http://www.d-programming-language-china.org ) 4 Standard Sections标准节 为了格式的一致性和可预测性，有一些标准节。 1.1 列出声明作者. [Copy to clipboard] [ - ]CODE: /** * Authors: Melvin D. Nerd, melvin@mailinator.com */ 1.2 Bugs: 列出已知的bug: [Copy to clipboard] [ - ]CODE: /** * Bugs: Doesn't work for negative values. */ 1.3 Date日期: 指定当前版本的日期，应该符合std.date的语法 [Copy to clipboard] [ - ]CODE: /** * Date: March 14, 2003 */ 1.4 Deprecated: Provides an explanation for and corrective action to take if the associated declaration is marked as deprecated. [Copy to clipboard] [ - ]CODE: /** * Deprecated: superseded by function bar(). */ deprecated void foo() { ... } 1.5 Examples示例: 任意使用示例( 本文出处: http://www.d-programming-language-china.org ) [Copy to clipboard] [ - ]CODE: /** * Examples: * -------------------- * writefln("3"); // writes '3' to stdout * -------------------- */ 1.6 History历史: 修订历史 [Copy to clipboard] [ - ]CODE: /** * Historys initial version * * V2 added feature X */ 1.7 License许可 版权许可信息 [Copy to clipboard] [ - ]CODE: ** Liense se freely for any purpose */ void bar() { ... } 1.8 Returns返回: 说明函数返回值。如果返就必说明了。 [Copy to clipboard] [ - ]CODE: /** * Read the file. * Returns: The contents of the file. */ void[] readFile(char[] filename) { ... } 1.9 See_Also参见 [Copy to clipboard] [ - ]CODE: /** * See_Also: * foo, bar, http://www.digitalmars.com/d/phobos/index.html */ 2.0 Standards标准: If this declaration is compliant with any particular standard, the description of it goes here. [Copy to clipboard] [ - ]CODE: /** * Standards: Conforms to DSPEC-1234 */ 2.1 Throws抛出: 列出什么情况下抛出什么异常( 本文出处: http://www.d-programming-language-china.org ) [Copy to clipboard] [ - ]CODE: /** * Write the file. * Throws: WriteException on failure. */ void writeFile(char[] filename{ . } 2.2 Verion版本 列出明的版本 [Copy to clipboard] [ - ]CODE: /** * Version: 1.6a */ 5 Special Sections特定节 一些节有特定含义和语法。( 本文出处: http://www.d-programming-language-china.org ) 1.1 Copyright版权: This contains t copyrht noti. TheacroOYRIT i set to te contets of he secion when it documents the module declaration. The copyright section only gets tis specal treaten whe i isfor h modle delaratin. [Copy to clipboard] [ - ]CODE: /** Copyright: Public Domain */ module foo; 1.2 Params参数: 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. [Copy to clipboard] [ - ]CODE: /*********************************** * foo does this. * Params: * x = is for this * and not for that * y = is for that */ void foo(int x, int y) { } <code> 1.3 Macros宏: The macros section follows the same syntax as the Params: section. It's a series of NAME=value pairs. The NAME is the macro name, and value is the replacement text. <code> /** * Macros: * FOO = now is the time for * all good men * BAR = bar * MAGENTA = <font color=magenta></font> */ Higliging高亮 1 Embeded Comments嵌入注释 可以用$(DDOCOMMENT comment text)语法来嵌入注释。注释不能嵌套。( 本文出处: http://www.d-programming-language-china.org ) 2 Embedded Code嵌入代码 可以用至少三个连字符来画出嵌入代码的范围。 [Copy to clipboard] [ - ]CODE: ++++++++++++++++++ + Or fution + Exle: + --------------------- imrt std.stdio; + +void foo() { + wrefln("foo!"); / print the sring */ + } + ------------------------ +/ 提示：用/++...+/的文档注释形式，所以/*...*/能包含在里面。 3 Embedded HTML嵌入HTML HTML可以嵌入么文档注释中，并且原封不动地输出。 However, since it is not necessarily true that HTML wil be thedesired outut format f the embedde documentatocommentxtractor, is best ovoi using itwre pracical [Copy to clipboard] [ - ]CODE: /** xample of embedded HTML: * * <li> <a href="http://www.digitalmars.com">Digital Mars</a> </li> * <li> <a href="http://www.classicempire.com">Empire</a> </li> * */ 4 Emphasis强调 Identifisdocumtn mnts at 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 hyperli . Ho emphasized depends on what it is -ction 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. 5 Character Entities字符实体 Some characters have special meaning to the documentation processor, to avoid confusion it can be best to replace them with their corresponding character entities:( 本文出处: http://www.d-programming-language-china.org ) Character Entity < &lt; > &gt; & &amp; It is not necessary to do this inside a code section, or if the special character is not immediately followed by a # or a letter.Macros宏 The documentation comment processor includes a simple macro text preprocessor. When a $(NAME) appears in section text it is replaced with NAME's corresponding replacement text. The replacement text is then recursively scanned for more macros. If a macro is recursively encountered, with no argument or with the same argument text as the enclosing macro, it is replaced with no text. Macro invocations that cut across replacement text boundaries are not expanded. If the macro name is undefined, the replacement text has no characters in it. If a $(NAME) is desired to exist in the output without being macro expanded, the $ should be replaced with $. Macros can have arguments. Any text from the end of the identifier to the closing ')' is the $0 argument. A $0 in the replacement text is replaced with the argument text. If there are commas in the argument text, $1 will represent the argument text up to the first comma, $2 from the first comma to the second comma, etc., up to $9. $+ represents the text from the first comma to the closing ')'. The argument text can contain nested parentheses, "" or '' strings, comments, or tags. If stray, unnested parentheses are used, they can be replaced with the entity ( for ( and ) for ). 宏定义按照顺序定义在下列地方： Predefined macros. Definitions from file specified by sc.ini's DDOCFILE setting. Definitions from *.ddoc files specified on the command line. Runtime definitions generated by Ddoc. Definitions from any Macros: sections.( 本文出处: http://www.d-programming-language-china.org ) Macro redefinitions replace previous definitions of the same name. This means that the sequence of macro definitions from the various sources forms a hierarchy. Macro names beginning with "D_" and "DDOC_" are reserved. 1 Predefined Macros预定义宏 These are hardwired into Ddoc, and represent the minimal definitions neede by Ddoc to format and highlight the presentation. The definitions are for simple HTML. [Copy to clipboard] [ - ]CODE: B = <b>$0</b> I = <i>$0</i> U = <u>$0</u> P = <p>$0</p> DL = <dl>$0</dl> DT = <dt>$0</dt> DD = <dd>$0</dd> TABLE = <table>$0</table> TR = <tr>$0</tr> TH = <th>$0</th> TD = <td>$0</td> OL = <ol>$0</ol> UL = <ul>$0</ul> LI = <li>$0</li> BIG = <big>$0</big> SMALL = <small>$0</small> BR = <br> LINK = <a href="$0">$0</a> LINK2 = <a href="$1">$+</a> RED = <font color=red>$0</font> BLUE = <font color=blue>$0</font> GREEN = <font color=green>$0</font> YELLOW =<font color=yellow>$0</font> BLACK = <font color=black>$0</font> WHITE = <font color=white>$0</font> D_CODE = <pre class="d_code">$0</pre> D_COMMENT = $(GREEN $0) D_STRING = $(RED $0) D_KEYWORD = $(BLUE $0) D_PSYMBOL = $(U $0) D_PARAM = $(I $0) DDOC = <html><head> <META http-equiv="content-type" content="text/html; charset=utf-8"> <title>$(TITLE)</title> </head><body> <h1>$(TITLE)</h1> $(BODY) </body></html> DDOC_COMMENT = <!-- $0 --> DDOC_DECL = $(DT $(BIG $0)) DDOC_DECL_DD = $(DD $0) DDOC_DITTO = $(BR)$0 DDOC_SECTIONS = $0 DDOC_SUMMARY = $0$(BR)$(BR) DDOC_DESCRIPTION = $0$(BR)$(BR) DDOC_AUTHORS = $(B Authors:)$(BR) $0$(BR)$(BR) DDOC_BUGS = $(RED BUGS:)$(BR) $0$(BR)$(BR) DDOC_COPYRIGHT = $(B Copyright:)$(BR) $0$(BR)$(BR) DDOC_DATE = $(B Date:)$(BR) $0$(BR)$(BR) DDOC_DEPRECATED = $(RED Deprecated:)$(BR) $0$(BR)$(BR) DDOC_EXAMPLES = $(B Examples:)$(BR) $0$(BR)$(BR) DDOC_HISTORY = $(B History:)$(BR) $0$(BR)$(BR) DDOC_LICENSE = $(B License:)$(BR) $0$(BR)$(BR) DDOC_RETURNS = $(B Returns:)$(BR) $0$(BR)$(BR) DDOC_SEE_ALSO = $(B See Also:)$(BR) $0$(BR)$(BR) DDOC_STANDARDS = $(B Standards:)$(BR) $0$(BR)$(BR) DDOC_THROWS = $(B Throws:)$(BR) $0$(BR)$(BR) DDOC_VERSION = $(B Version:)$(BR) $0$(BR)$(BR) DDOC_SECTION_H = $(B $0)$(BR)$(BR) DDOC_SECTION = $0$(BR)$(BR) DDOC_MEMBERS = $(DL $0) DDOC_MODULE_MEMBERS = $(DDOC_MEMBERS $0) DDOC_CLASS_MEMBERS = $(DDOC_MEMBERS $0) DDOC_STRUCT_MEMBERS = $(DDOC_MEMBERS $0) DDOC_ENUM_MEMBERS = $(DDOC_MEMBERS $0) DDOC_TEMPLATE_MEMBERS = $(DDOC_MEMBERS $0) DDOC_PARAMS = $(B Params:)$(BR)\n$(TABLE $0)$(BR) DDOC_PARAM_ROW = $(TR $0) DDOC_PARAM_ID = $(TD $0) DDOC_PARAM_DESC = $(TD $0) DDOC_BLANKLINE = $(BR)$(BR) DDOC_PSYMBOL = $(U $0) DDOC_KEYWORD = $(B $0) DDOC_PARAM = $(I $0) 2 Basic Formatting Macros B boldface the argument I italicize the argument U underline the argument P argument is a paragraph DL argument is a definition list DT argument is a definition in a definition list DD argument is a description of a definition TABLE argument is a table TR argument is a row in a table TH argument is a header entry in a row TD argument is a data entry in a row OL argument is an ordered list UL argument is an unordered list LI argument is an item in a list BIG argument is one font size bigger SMALL argument is one font size smaller BR start new line LINK generate clickable link on argument LINK2 generate clickable link, first arg is address RED argument is set to be red BLUE argument is set to be blue GREEN argument is set to be green YELLOW argument is set to be yellow BLACK argument is set to be black WHITE argument is set to be white D_CODE argument is D code DDOC overall template for output DDOC is special in that it specifies the boilerplate into which the entire generated text is inserted (represented by the Ddoc generated macro BODY). For example, in order to use a style sheet, DDOC would be redefined as:( 本文出处: http://www.d-programming-language-china.org ) [Copy to clipboard] [ - ]CODE: DDOC = <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd"> <html><head> <META http-equiv="content-type" content="text/html; charset=utf-8"> <title>$(TITLE)</title> <link rel="stylesheet" type="text/css" href="style.css"> </head><body> <h1>$(TITLE)</h1> $(BODY) </body></html> DDOC_COMMENT is used to insert comments into the output file. Highlighting of D code is performed by the following macros: 3 D Code Formatting Macros D_COMMENT Highlighting of comments D_STRING Highlighting of string literals D_KEYWORD Highlighting of D keywords D_PSYMBOL Highlighting of current declaration name D_PARAM Highlighting of current function declaration parameters The highlighting macros start with DDOC_. They control the formatting of individual parts of the presentation. 4 Ddoc Section Formatting Macros DDOC_DECL Highlighting of the declaration. DDOC_DECL_DD Highlighting of the description of a declaration. DDOC_DITTO Highlighting of ditto declarations. DDOC_SECTIONS Highlighting of all the sections. DDOC_SUMMARY Highlighting of the summary section. DDOC_DESCRIPTION Highlighting of the description section. DDOC_AUTHORS .. DDOC_VERSION Highlighting of the corresponding standard section. DDOC_SECTION_H Highlighting of the section name of a non-standard section. DDOC_SECTION Highlighting of the contents of a non-standard section. DDOC_MEMBERS Default highlighting of all the members of a class, struct, etc. DDOC_MODULE_MEMBERS Highlighting of all the members of a module. DDOC_CLASS_MEMBERS Highlighting of all the members of a class. DDOC_STRUCT_MEMBERS Highlighting of all the members of a struct. DDOC_ENUM_MEMBERS Highlighting of all the members of an enum. DDOC_TEMPLATE_MEMBERS Highlighting of all the members of a template. DDOC_PARAMS Highlighting of a function parameter section. DDOC_PARAM_ROW Highlighting of a name=value function parameter. DDOC_PARAM_ID Highlighting of the parameter name. DDOC_PARAM_DESC Highlighting of the parameter value. DDOC_PSYMBOL Highlighting of declaration name to which a particular section is referring. DDOC_KEYWORD Highlighting of D keywords. DDOC_PARAM Highlighting of function parameters. DDOC_BLANKLINE Inserts a blank line.( 本文出处: http://www.d-programming-language-china.org ) For example, one could redefine DDOC_SUMMARY: [Copy to clipboard] [ - ]CODE: DDOC_SUMMARY = $(GREEN $0) And all the summary sections will now be green. 5 Macro Definitions from sc.ini's DDOCFILE A text file of macro definitions can be created, and specified in sc.ini: [Copy to clipboard] [ - ]CODE: DDOCFILE=myproject.ddoc 6 Macro Definitions from .ddoc Files on the Command Line File names on the DMD command line with the extension .ddoc are text files that are read and processed in order. 7 Macro Definitions Generated by Ddoc BODY Set to the generated document text. TITLE Set to the module name. DATETIME Set to the current date and time. YEAR Set to the current year. COPYRIGHT Set to the contents of any Copyright: section that is part of the module comment. DOCFILENAME Set to the name of the generated output file.( 本文出处: http://www.d-programming-language-china.org )Using Ddoc for other Documentation 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. 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. 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. References CandyDoc is a very nice example of how one can customize the Ddoc results with macros and style sheets. http://www.dsource.org/projects/helix/wiki/CandyDoc( lastupdate:20070426 最新文章请访问http://www.d-programming-language-china.org )关于一大步成功社区:yidabu提倡在交流中学习，在分享中提高收集感兴趣的知识，写下心得，通过网络与别人一起分享理解一点就实践一步，收获什么就分享什么，成功就是这样一点点一步步累积起来的网络只是一个工具，只有自己身心提高才是实实在在的。d-programming-language-china.org为大家提供一个学习交流各种知识的平台