Ruby注释的写法 Markup

Ruby注释的写法　Markup

自然地书写注释。
源英文链接

段落是指具有相同左缩进的文本。在该缩进之后的是格式化的文本。

• 列表的标记为：

  • ’*’ or ‘-’ 表示着重号列表
  • 数字加圆点用于数字列表

比如, 产生上述文本的命令是:

1. 列表的标记为：

   * '*' or '-' 表示着重号列表
   * 数字加圆点用于数字列表

• 带标签列表，也称描述列表为方括号加标签，　如：

   [cat]   small domestic animal
   [+cat+] command to copy standard input

• 带标签列表也可以描述为在标签后加上双冒号。该格式下是tab作为分隔符，因此所有的描述都排列整齐。

   cat::   small domestic animal
   +cat+:: command to copy standard input

• 对于两种标签列表，如果正文开始与标签相同的行，那么文本的开始决定了剩余文本的缩进。后续的文本也开始于该标签之后。下面两个都是有效标签列表。

     <tt>--output</tt> <i>name [, name]</i>::
         specify the name of one or more output files. If multiple
         files are present, the first is used as the index.
  
     <tt>--quiet:</tt>:: do not output the names, sizes, byte counts,
                         index areas, or bit ratios of units as
                         they are processed.
  

• 标题利用多个等号表示

  = 一级标题
  == 二级标题
  

• 垂直分割线用三个或者更多的连字符

• 非普通文本可以被markd up，如：

  斜体     _word_  \<em>text</em>
  加粗      *word* or \<b>text</b>
  打印字体   +word+ or \<tt>text</tt>

• 类名，源文件，以及任意包含下划线或者前缀有#字符的都会被自动添加超链接。
  以 http:, mailto:, ftp:, or www. 开始的超链接会自动识别。HTTP链接为图片时，会自动添加图片标签。路径是相对路径。H超链接也可以是　label[url], 其中 label 是显示的文本, url 是目标链接.

• 方法参数列表会被自动提取，如果有yield，那么块名也会被提取。如:

   def fred
     ...
     yield line, address

产生的文档为：

   fred() { |line, address| ... }

你也可以在方法定义后利用 ‘:yields: …’ 来重写参数名，如：

   def fred      # :yields: index, position
     ...
     yield line, address

产生的文档为：

    fred() { |index, position| ... }

其中：
':yields:' 是文档修饰符的例子. 修饰符出现在#之后。其他的修饰符还包括
:nodoc:[all]将不会包含后面的文档。比如对于下列代码

     module SM  #:nodoc:
       class Input
       end
     end
     module Markup #:nodoc: all
       class Output
       end
     end

上述代码中，只有 class SM::Input 会出现在文档中

:doc:强制添加文档. 如果想在文档中包含私有方法，这是有用的.
:notnew:
仅仅适用于构建方法。正常情况下，RDOC方法假设initialize的参数作为new方法的参数。因而会添加一个new方法，通过该修饰符阻止这种做法。 注意initialize方法不会被显示在文档中，除非你使用-a命令行选项。

RDOC通过#--阻止之后的注释添加到文档中去，通过#++恢复

注释也可以包含文件。
:include:filename
将会包含明明文件的内容. 该文件会 --include 选项的路径进行搜索,或者默认是当前路径.

:title:text
设置文档标题. E等价于 --title 命令行参数. (命令行参数优先级最高).
:main:name　等价于 --main 命令行参数。