README

一个从XML文件集合生成API参考文档的系统。

理由

API文档很重要。一个软件库文档的质量会极大地影响潜在程序员开始使用它的速度，而这种速度又极大地影响库是否会被使用。

目前，有两种主要方法来生成API文档。第一种是像编写项目其他文档一样手动编写。另一种是在项目的源代码中插入特殊格式的注释，并从这些注释生成文档。（例如Doxygen、javadoc和PHPDocumentor。）在我看来，这两种方法都存在很大的缺陷。

在第一种方法中，API规范中的错误很容易被忽略。这是因为通用的文档格式并不是为处理编程API而设计的，而编程API必须非常严格地定义。此外，程序员很容易在源代码中更改API，而忘记更新文档。

在行内文档的情况下，一个文件中混入了两种不同的语法，这是一种令人不快的情况。理由是程序员应该同时在更改源代码时更新文档，但同样，没有保证这一点。这种方法比第一种方法的好处是，API至少是严格定义的，尽管它可能仍然会过时。

将API文档与源代码混合通常至少会导致以下问题之一

由于大量的屏幕空间用于文档注释，源代码变得难以阅读。
API文档不充分，因为程序员试图最小化源代码的污染。也就是说，行内文档几乎不作为文档的理由。

此外，行内文档可能会鼓励缺乏适当的传统源代码注释。 - 对库本身工作的程序员有用的注释与API文档的性质非常不同。

相反，我提出了一种替代方法。我们不必在主要文档中松散地定义API，也不必在源代码中的第二种语法中严格定义API，我们可以在源代码文件旁边维护一组API文档文件，并在那里严格定义我们的API。例如。

project/src/some_file.php  # Some source code file
project/src/some_file.xml  # The strict specification of the API along with
                           # documentation

或者，可以提供单独的目录来实现这一目的，就像许多人将单元测试与主源代码分离一样。例如。

project/src/some_file.php      # Some source code file
project/src-doc/some_file.xml  # The strict specification of the API along
                               # with documentation

这种方法有以下优点

API文档可以使用自己的严格定义的语法，从而确保规范的有效性。
源代码语法和文档语法不再混同于同一文件中。源代码可以再次变得美观和简洁，注释也真正有用。
可以在单元测试中对文档的一致性进行测试。（大多数通用编程语言都有用于读取XML文件的库。）这使得确保文档的正确性变得容易得多。

初始实现

本项目是该想法的初步实现。我正在用它来记录我编写的PHP库。（尽管该系统对许多其他语言也应该同样有效。）它非常适合我的需求，但我必须强调，它主要是使用XSLT和GNU Bash拼凑而成的。也就是说，这不是最优雅的实现方式。我怀疑它只能在GNU/Linux系统上运行，尽管在其他*nix系统和Cygwin环境中可能也可以使用。

主要要求如下

GNU Bash
xmllint (libxml)
xsltproc (libxml)

它将源文档编译成另一种文档格式，以便将其纳入项目的主要文档中。在撰写本文时，唯一支持的格式是PhD使用的Docbook格式（这是生成php.net所用的格式）。

安装

除了通过git检出代码外，还可以通过运行以下命令从您的项目主目录安装它：

php ./path/to/composer.phar require daniel-ac-martin/apidoc
php ./path/to/composer.phar install

然后可以通过输入以下命令运行apidoc：

vendor/bin/apidoc

用法

主脚本文件apidoc是一个bash脚本。可以通过执行"apidoc -h"来获取完整的用法信息。

通常，您会在项目的根目录中创建一个名为"apidoc.xml"的XML文件，apidoc将从其中获取信息。（或者，您可以通过程序的参数提供信息来调用程序。）以下是配置文件的一个示例

<?xml version="1.0" encoding="UTF-8"?>
<apidoc-config>
	<source>
		<directory filter="*.xml">src-doc</directory>
	</source>
	<transformations>
		<transform template="phpnet">build/doc</transform>
	</transformations>
</apidoc-config>

这将查找src-doc/目录中以".xml"结尾的源文件。然后它将汇总它们，并使用名为"phpnet"（在撰写本文时是唯一有效的模板）的模板进行转换。转换后的文件（包括任何中间步骤）将被放置在build/doc/目录中。然后用户可以将生成的API文档插入到项目的主要文档中。

许可协议

根据GNU通用公共许可证第3版或任何后续版本分发。

daniel-ac-martin / apidoc

维护者

详细信息

README

理由

初始实现

安装

用法

许可协议