使用ApiGen生成文档

If you’ve ever worked with someone else’s code, you know the pain (or pleasure) of missing (or existing) documentation. Well documented code is one of the cornerstones of professional software development, and unless you learn how to document your code so that it becomes second nature, you’re doing yourself and others more harm than good.

如果您曾经使用过别人的代码，那么就会知道缺少(或现有)文档的痛苦(或愉悦)。 记录良好的代码是专业软件开发的基石之一，除非您学习如何记录代码以使其成为第二自然，否则对您自己和他人的危害大于好处。

If this sounds overly discouraging, it’s because it should be. If you’re writing undocumented code, you should stop this very moment. I’m serious. Drop everything, save and quit, and focus on improving this essential part of your workflow.

如果这听起来过于令人沮丧，那是因为应该这样做。 如果您要编写未公开的代码，则应立即停止。 我是认真的。 删除所有内容，保存并退出，并专注于改进工作流的这一重要部分。

Over the years, I’ve had to suffer through horrible documentation (hello, Zend Framework!) and have glided through some pretty solid stuff as well (thank you, Swift Mailer!). I try to document every single file I produce, and I’ve been doing it long enough now that it has become second nature. I have a strict documentation standard I follow, one that is compatible with ApiGen, the documentation generator, and one that is highly human-readable but also fully compatible with modern IDEs. This means I can generate my library documentation for the public along with examples, tutorials, descriptions and possible errors with a single command.

多年来，我不得不经历糟糕的文档(您好，Zend Framework！)，并且还浏览了一些非常可靠的内容(谢谢您，Swift Mailer！)。 我尝试记录我生成的每个文件，并且由于它已成为第二性质，所以我已经做了很长时间了。 我遵循一个严格的文档标准，该标准与ApiGen，文档生成器兼容，以及一个高度可读的，但也与现代IDE完全兼容的标准。 这意味着我可以通过一个命令为公众生成我的图书馆文档以及示例，教程，说明和可能的错误。

ApiGen is a docblock parser like PhpDocumentor. PhpDocumentor has been around for much longer than ApiGen, but unfortunately its development is somewhat stunted and it lacks in terms of modern documentation and examples. It also has some unpleasant dependencies which can cause problems on fresh PHP installations, and often throws errors that aren’t documented anywhere. You can find out more about the PhpDocumentor in a previous SitePoint article. As for which is better… I believe ApiGen to be the logical choice due to the following downsides of PhpDocumentor:

ApiGen是像PhpDocumentor这样的docblock解析器。 PhpDocumentor的存在时间比ApiGen长得多，但是不幸的是，它的开发有些停滞，并且缺乏现代文档和示例。 它还具有一些令人不愉快的依赖关系，这些依赖关系可能会导致在全新PHP安装上出现问题，并经常引发任何地方都未记录的错误。 您可以在上一篇SitePoint文章中找到有关PhpDocumentor的更多信息。 至于哪个更好……由于PhpDocumentor具有以下缺点，我相信ApiGen将是合理的选择：

• requires page-level docblocks (above namespaces) that serve no purpose; they are never properly parsed and the entered descriptions are nowhere to be found. Update, August 24th 2012: a commenter has pointed out that page-level blocks are in fact used in templates other than the default. They are still, however, not essential, and generate errors when PhpDoc is parsing, staying in the documentation as logged errors indefinitely.

  需要页面级文档块(名称空间上方) 没有任何目的； 永远不会正确地解析它们，并且在任何地方都找不到输入的描述 。 2012年8月24日更新：评论者指出，页面级块实际上是在默认模板之外的模板中使用的。 但是，它们仍然不是必需的，并且在PhpDoc进行解析时会生成错误，并无限期地将其作为记录的错误保留在文档中。

• no search in the generated documentation.
  在生成的文档中没有搜索。

• layout errors – long package names break the “Api Documentation” drop-down menu, the generated GraphViz charts will have a Z-index higher than the menus and will thus appear above them even when the menus are expanded (see note below)

  布局错误–较长的程序包名称破坏了“ Api文档”下拉菜单，生成的GraphViz图表的Z索引高于菜单，因此即使展开菜单，它们也将显示在菜单上方 (请参阅下面的注释)

• fails to recognize some type hinting for unknown reasons. (this is fixed in alpha8, see note below)

  由于未知原因而无法识别某种类型的提示。 (这已在alpha8中修复，请参见下面的注释)

• no html support in tag descriptions – HTML tags stay visible, so advanced formatting is not possible from what I’ve noticed. (see note below)

  标记说明中没有html支持– HTML标记保持可见，因此从我注意到的内容来看，无法进行高级格式化。 (请参阅下面的注释)

Note, Aug. 24th: Most of these issues have been fixed in the last version I tested – alpha 10. However, the lack of a search function is still a deal breaker for me.

请注意，8月24日：大多数问题已在我测试的最新版本(alpha 10)中得到了解决。但是，缺少搜索功能仍然是我的难题。

Docblocks和标签 (Docblocks and Tags)

We’ll be using a couple classes I wrote for the purpose of this tutorial spread out across a couple folders under two simple namespaces. These classes won’t be a whole lot of use in the real world, but they’ll serve us well for this article. Since the classes are rather large with all the comments and spacing dictated by the PSR-2 standard, I’ve uploaded