使用 haxe dox 来构建 API 文档. 参考这个库的 Readme 你能直接获得最新Haxe API.

• 参考 gen.hxml 如何从 hx源码中导出 xml 文件,

• 参考 std.hxml 如何获得 API HTML

• dox 默认的模板使用的 CSS 框架为 bootstrap 2.3.2

• https://github.com/dpeek/dox/wiki/Using-Dox

注释规范

这些注释规范主要针对 haxelib dox解析

• 由于 dox 使用了 markdown 解析注释, 因此可以使用 markdown 语法

  # 表格, 好像只支持 左 或 右对齐
  First Header  | Second Header
  -----------:  | :------------
  Content Cell  | Content Cell
  Content Cell  | Content Cell
  
  # 一些基本的 HTML 标签
  To <b>edit</b> settings, press `Ctrl + ,`
  
  # URL 引用 (TODO: 如何引用当前手册中的链接?)
  [example](http://example.com)
  

• 元数据, 大多数情况下不需要写这些, 解析器能识别各参数或回值类型

  @since name 1.2.3 aplha		# 需要正确的版本号格式 n.n.n
  @exception TypeName 描述		# 或 @throws
  @param delay 写参数名就行了
  @return 一些描述内容			# 或 @returns
  @see TypeName				#
  @deprecated 弃用描述			# 不用理会这个的顺序
  

导出XML

简单的示例

haxe -xml doc.xml --macro include('my.package') -D doc-gen -dce no

大的项目时参考 dox 下的 gen/ImportAll.hx 生成, 以及一些构建示例

读取XML

不需要做这一步, 但是如果你打算从 xml 读取一些内容时可以尝试

class DocGen {
    static function main() {
        var data = sys.io.File.getContent("doc.xml");
        var doc = Xml.parse(data).firstElement();
        var parser = new haxe.rtti.XmlParser();
        parser.process(doc,"js");	//附加的参数 "js", 表示为平台,
									//process 可以被多次调用(每个平台调用一次)
    }
}

dox 命令行

你可以不必安装这个库, 下载 theme 文件夹 和 run.n 文件就可以了, 并用 neko run.n 来替换 haxelib run dox

• 命令为: neko run.n -i export.xml

  # 最终输出文件 e.g: -o bin/api-laster.zip 或者为目录 -o bin/docs
  [-o |  --output-path] <path>
  
  # XML 所在目录。 e.g： -i bin/xmls
  [-i | --input-path] <path>
  
  #Add template directory
  [-t | --template-path] <path>
  
  # Add a resource directory whose contents are copied to the output directory
  [-res | --resource-path] <dir>
  
  #Add a path include filter, EReg String
  [-in | --include] <path>
  
  #Add a path exclude filter, EReg String. e.g: -ex ^js -ex flash
  [-ex | --exclude] <path>
  
  #Set the page main title
  --title <name>
  
  #Set the package which serves as top-level
  --toplevel-package <dotPath>
  
  #Set the theme name or path, 设置模板
  -theme <name>
  
  #Defines key = value
  [-D  | --defines] <key> <value>
  
  # 其它
  -D source-path 	#将定义源码URL
  

模板修改

由于引用了 Google 文件,而国内却无法访问.因此可以做一些改动。

Old Makefile

由于 使用 -in 代替了 -ex , 因此不再需要这份旧的文件

CC  := neko gendoc.n

# --> 修改 TARGET_DIR 为你要输出的目录,注意: haxe dox  不支持 cygwin环境下跨磁盘的的目录
TARGET_DIR  :=  ./api-h3d

# --> 修改 FILES 为 你用 haxe -xml 生成的 xml 文件. 目录/文件名
FILES   := pkgs.xml


TARGET  :=  $(TARGET_DIR)/index.html


# 赋值空格
EMPTY:=
SPACE:= $(EMPTY) $(EMPTY)

#排除这些不要的类
EX := microsoft javax haxe flash format hxsl Array ArrayAccess Bool Class Dynamic EReg Enum EnumValue Float
EX += IMap Int Iterable Iterator Lambda List Map Math Null Reflect Std String StringBuf
EX += StringTools Type UInt ValueType Void Xml XmlType Date

EXCLUDE := $(addprefix -ex$(SPACE),$(EX))

all : $(TARGET)

$(TARGET):
    $(CC) -i $(FILES) -o $(TARGET_DIR) $(EXCLUDE)

clean:
    @echo clean...
    @rm -rf $(TARGET_DIR)