direktori cari
Ruby用户指南 3、开始 4、简单的例子 5、字符串 6、正则表达式 7、数组 8、回到那些简单的例子 9、流程控制 10、迭代器 11、面向对象思维 12、方法 13、类 14、继承 15、重载方法 16、访问控制 17、单态方法 18、模块 19、过程对象 20、变量 21、全局变量 22、实变量 23、局部变量 24、类常量 25、异常处理:rescue 26、异常处理:ensure 27、存取器 28、对象的初始化 29、杂项 RGSS入门教程 1、什么是RGSS 2、开始:最简单的脚本 3、数据类型:数字 4、数据类型:常量与变量 5、数据类型:字符串 6、控制语句:条件分歧语句 7、控制语句:循环 8、函数 9、对象与类 10、显示图片 11、数组 12、哈希表(关联数组) 13、类 14、数据库 15、游戏对象 16、精灵的管理 17、窗口的管理 18、活动指令 19、场景类 Programming Ruby的翻译 Programming Ruby: The Pragmatic Programmer's Guide 前言 Roadmap Ruby.new 类,对象和变量 容器Containers,块Blocks和迭代Iterators 标准类型 深入方法 表达式Expressions 异常,捕捉和抛出(已经开始,by jellen) 模块 基本输入输出 线程和进程 当遭遇挫折 Ruby和它的世界 Ruby和Web开发 Ruby Tk Ruby 和微软的 Windows 扩展Ruby Ruby语言 (by jellen) 类和对象 (by jellen) Ruby安全 反射Reflection 内建类和方法 标准库 OO设计 网络和Web库 Windows支持 内嵌文档 交互式Ruby Shell 支持 Ruby参考手册 Ruby首页 卷首语 Ruby的启动 环境变量 对象 执行 结束时的相关处理 线程 安全模型 正则表达式 字句构造 程序 变量和常数 字面值 操作符表达式 控制结构 方法调用 类/方法的定义 内部函数 内部变量 内部常数 内部类/模块/异常类 附加库 Ruby变更记录 ruby 1.6 特性 ruby 1.7 特性 Ruby术语集 Ruby的运行平台 pack模板字符串 sprintf格式 Marshal格式 Ruby FAQ Ruby的陷阱
watak

Embedded Documentation



Figure not available...

Figure not available...

So you've written a masterpiece, a class in a class of its own, and you'd like to share it with the world. But, being a responsible developer, you feel the need to document your creation. What do you do? The simplest solution is to use Ruby's built-in documentation format, RD, and rdtool, a Ruby utility suite that converts this documentation into a variety of output formats.

rdtool scans a file for =begin and =end{=begin...=end@{=begin pairs, and extracts the text between them all. This text is assumed to be documentation in RD format. The text is then processed according to a simple set of rules:

  • Lines of text flush to the left margin are converted to paragraphs.
  • Lines starting with one to four equals signs are headings. ``='' is a first-level heading, ``=='' a second-level heading, and so on. ``+'' and ``++'' can be used to signal fifth- and sixth-level headings if you really want to go that deep.

    = Top Level Heading
    == Second Level Heading
    ...
    
  • Lines in which the first nonspace is an asterisk indicate the beginnings of bullet lists. Continuation lines for each bullet item should line up with the text on the first line. Lists may be nested.

    This is normal text
    * start of a
      multiline bullet item
    * and another
      * nested item
      * second nested
    * third item at top level
    
  • Lines where the first nonspace characters are digits between parentheses indicate numbered lists. The actual digits used are ignored. Again, lists may be nested.

    (1) A numbered item
        * subitem in a bulleted list
        * subitem
    (2) Second numbered item
    (9) This will actually be labeled '3.'
    
  • Lines starting with a colon indicate labeled lists. The text on the colon line is the label. The immediately following text (which may not be indented less than the label) is the descriptive text. Again, each type of list may be nested.

    : red
      when the light is red, you
      must stop
    : amber
      the amber light means that things are about to change. Either:
      * step on the gas, or
      * slam on the brakes
    : green
      green means GO
    
  • Lines starting with three minus signs are a special kind of labeled list, when the labels are method names and signatures. The source in Figure A.1 on page 512 shows a handful of these in action.

Indented text that isn't part of a list is set verbatim (such as the stuff under ``Synopsis'' in Figures A.1 and A.2).

Inline Formatting

Within blocks of text and headings, you can use special inline sequences to control text formatting. All sequences are nested within a set of double parentheses.

Sequence Example Intended Use
((*emphasis*)) emphasis Emphasis (normally italic)
(({code stuff})) code stuff Code
((|variable|)) variable Variable name
((%type me%)) type me Keyboard input
((:index term:)) index term Something to be indexed
((<reference>)) reference Hyperlink reference
((-footnote-)) text.4 Footnote text. A reference is placed inline, and the text of the footnote appears at the bottom of the page.
(('verb')) verb Verbatim text

Cross References

The content of headings, the labels of labeled lists, and the names of methods are automatically made into potential cross reference targets. You make links to these targets from elsewhere in the document by citing their contents in the ((<...>)) construct.

= Synopsis
...
See ((<Return Codes>)) for details.
..
== Instance Methods

--- Tempfile.open( filename )     Opens the file...

== Return Codes .. The method ((<Tempfile.open>)) raises an (({IOException}))...

If a reference starts with ``URL:'', rdtool attempts to format it as an external hyperlink.

The reference ((<display part|label>)) generates a link to label but places the text ``display part'' in the output document. This is used in the description section of the example in Figure A.1 on page 512 to generate references to the method names:

perspective, apart from the unusual ((<(({new}))|Tempfile.new>)),
...

This construct displays the word ``new'' in code font but uses it as a hyperlink to the method Tempfile.new.

Method Names

rdtool makes certain assumptions about the format of method names. Class or module methods should appear as Class.method, instance methods as Class#method, and class or module constants as Class::Const.

--- Tempfile::IOWRITE
    Open the file write-only.
    ...
--- Tempfile.new( filename )
    Constructs a temporary file in the given directory. The file
    ...
--- Tempfile#open
    Reopens ((|aTempfile|)) using mode ``r+'', which allows reading
    ..

Including Other Files

The contents of filename will be inserted wherever the document contains

<<< filename

If the file is specified with an .rd or .rb extension, it will be interpreted as RD documentation.

If the filename has no extension, rdtool will look for a file with an extension that matches the type of output being produced (.html for HTML files, .man for man files, and so on) and interpolate that file's contents in the output stream. Thus, a line such as:

<<< header

could be used to add an output-dependent header to a document.

Using rdtool

RD documentation can be included directly in a Ruby source program or written into a separate file (which by convention will have the extension .rd). These files are processed using the rd2 command to produce appropriately formatted output.

rd2  [
            options
            ]  inputfile   [ >outputfile ]

Some common options include:

-r format Select an output format. -rrd/rd2html-lib.rb produces HTML output (the default). -rrd/rd2man-lib.rb produces Unix man page output.
-o name Set the base part of the output filename.
--help List the full set of options.

Mandatory Disclaimer

As we are writing this, RD and rdtool are undergoing continuous development. It is likely that some of the details we give here will be out of date (or just plain wrong) by the time you read this.

Included with the rdtool distribution is the file README.rd. We suggest you do so, as it will give you the current scoop on producing Ruby documentation.


Extracted from the book "Programming Ruby - The Pragmatic Programmer's Guide"
Copyright
Artikel sebelumnya: Artikel seterusnya: