README

设置
初始化
元素、对象和符号
DocBlocks
路由
性能

Documenter 是一个库（更像是扩展或包装），基于 phpDocumentor，截至本文撰写时，这是与 PHP 项目内联文档交互更受欢迎的基库。

有大量的生成器可用于为 PHP 项目创建文档站点。其中许多生成静态站点（HTML 或其他文件）以在网络上展示。这有两个主要原因：

内容是静态的（项目的 PHP 文件一旦捕获通常不会更改）
性能（大型项目可能包含数百甚至数千个文件）。

然而，当我们检查 8fold（以及其他一些项目）时，我们发现这两个考虑因素不再像以前那样有分量。随着 PHP 项目变得更加模块化，需要捕获文档的文件数量越来越少。此外，PHP 及其相关的 Zend 框架实际上非常快。最后，各种现代开发技术也可以减少生成文档对服务器的负载。（有关详细信息，请参阅性能部分。）

在 8fold，我们还发现了静态站点生成器的局限性，这激发了我们尝试不同的方法。

将 Documenter 添加到 PHP 项目中，并通过基于网络的 API 提供文档。将 Documenter 添加到动态网站中，并无缝集成（无需在动态内容交付和静态内容交付之间切换）。更改您的返回字符串或模板文件，而无需执行任何其他操作来更新所有项目版本到新的外观和感觉。

设置

$ composer require 8fold/documenter-php

或者将以下内容添加到您的 composer 文件的 require 部分，并运行 composer install 或 composer update

"8fold/documenter-php": "*"

建议将其添加到您的 PSR-4 声明中

"Eightfold\\DocumenterPhp\\": "vendor/8fold/documenter-php/src/"

Documenter 还使用以下内容

初始化

Documenter 的主入口类是位于 /src 中的 Documenter 类；请参阅文档了解所需信息。初始化后，您应该可以轻松地遍历事物。（在相对意义上。）

如果您在任何时候遇到困难，请更新文档或告知我们，我们将尽力改进体验。

元素、对象和符号

元素：可以具有相关 DocBlock 的代码片段。
对象：具有独立作用域的元素。
符号：具有从属作用域的元素。

例如，以下都是“对象”：

<?php

// Variable
$hello = 12;

// Function
function hello($int) { return $int; }

// Class_
class Hello {}

// Trait_
trait Hello {}

// Interface_
interface Hello {}

此外，对于符号；使用上面的class Hello

<?php

// Class_
class Hello {
  // Property
  $hello = 12;

  // Method
  function hello($int) { return $int; }
}

所有上述内容都是元素的表现。

文档块

文档块是文档化代码并使其为Documenter准备的主要方式。对于PHP，文档块出现在一个反斜杠后跟两个星号（/**）和一个单星号后跟一个反斜杠（*/）之间。进一步来说，它们位于被文档化的元素之上。

/**
 * This is the short description of the DocBlock.
 *
 * The long description begins one empty line (paragraph) below the short description.
 */
class HelloWorld
{
    /**
     * Short description
     */
    private function print()
    {
       // Comments such as these do not count.
    }
}

当谈到编写文档块的方式时，Documenter并不强加太多意见；因此，您可以阅读phpDocumentor文档以了解如何在代码中编写文档。

话虽如此，以下是在使用Documenter时需要考虑的一些事项。

@category: phpDocumentor已废弃使用@category标签。我们理解并同意废弃此标签的愿望，鉴于它最初设计的目的。然而，从语义上来说，这是用于将各种元素分组以生成站点的最合适的标签名称；因此，Documenter确实利用了此标签来对方法、属性、类、特性等进行分组。

注意：将类别视为页面上的部分，但要求您更新所有@category标签到@section似乎要求过高。

返回类型：如果您的方法在项目中返回对象的实例，您可以通过将此类型作为带反斜杠的完整类命名空间来记录，从而创建更健壮的用户体验。

// We have a class with a full name of: Hello\World\Class

/**
 * @return \Hello\World\Class
 */
public function instance() {}

当Documenter返回类型提示的字符串时，该字符串将是"Class"，表示它是在当前项目中的类。进一步，通过在获取显示字符串时将withLink参数设置为true，也将出现指向对象URL的链接。

<a href="/[project-slug]/[version-slug]/hello-world/class">Class</a>

对于不在项目作用域内的类，Documenter仍然只返回类名（不包含命名空间），但将名称用方括号括起来。

Something\Outside\The\Project\Space\SomeClass

变成

[SomeClass]

重要的是命名空间开头的反斜杠。此外，此功能适用于类的父类。

use Hello\World\Class

use Something\Outside\The\Project\Space\SomeClass 

class MyLocalClass extends Class
{

}

class MyExternalClass extends SomeClass
{

}

获取父类显示字符串的结果将与之前的输出相同。

路由

Documenter旨在帮助您生成网站；因此，所有可文档化的对象都可以生成URL。此URL仅用于生成链接，并不作为路由列表或路由生成器。话虽如此，如果您使用允许您使用属性生成路由的框架，则可以使用以下列表作为起点。

话虽如此，您不需要构建网站才能利用Documenter。

关于单视图URL的说明

为了帮助创建我们认为更好的用户体验，默认的URL生成是任何可文档化项目对象（Class_、Trait_、Interface_、Property、ClassMethod）都可以有自己的URL。这包括

类、
特性、
接口、
属性和
方法

注意：您不必以这种方式将文档站点分离；然而，在使用Documenter时请记住这一点。

关于命名空间的说明

由于PHP允许在同一项目中存在多个命名空间，因此决定将命名空间包含在URL中是最简单的方式，以便在同一项目文档中存在具有相同名称但不同命名空间的两个对象。
尽管命名空间被认为具有一定的层次性，但为URL生成的命名空间不会创建多个级别，这应该会使开发人员和网站用户更容易使用。

/{project-slug}/{project-version-slug} 这是特定项目版本生成的基本URL。

/{project-slug}/{project-version-slug}/{object-namespace}/{functions or properties}/{project-object-slug} 这是查看特定方法或属性（不由其他项目对象“拥有”）的URL。project-object-slug 是对象 name 转换为 slug 的 name。

注意：我们大多数项目都没有存在于类（Class）、特性（Trait）或接口（Interface）之外的函数或方法。因此，命名空间可能不是一个必要的考虑因素。将此分析放入 TODO 列表。

/{project-slug}/{project-version-slug}/{object-namespace}/{classes, traits, or interfaces}/{project-object-slug} 这是查看特定类（Class）、特性（Trait）或接口（Interface）的URL。

/{project-slug}/{project-version-slug}/{object-namespace}/{classes, traits, or interfaces}/{project-object-slug}/{methods or properties}/{project-object-slug} 这是查看特定类方法或属性的URL。

注意：文档器对象不会生成以下URL；但是，通过创建上述URL，它们成为了可能。（用户可以在浏览器中删除URL中的 project-object-slug 并尝试查看该页面，例如。）因此，如果您将文档器集成到具有路由提供者的PHP框架中，您可能还想考虑创建这些页面以改进网站的用户体验。

/{project-slug} 这是生成项目版本列表的前缀URL。

/{project-slug}/{project-version-slug}/{object-namespace} 这是创建给定命名空间内项目对象列表的前缀URL。

/{project-slug}/{project-version-slug}/{object-namespace}/{project-object-name} 这是允许创建项目中文件内找到的类（Class）、特性（Trait）、接口（Interface）、方法和方法属性对象列表的前缀URL。project-object-name 将是以下字符串之一，按实例化对象类型的顺序排列

类
特性
接口
函数
属性

/{project-slug}/{project-version-slug}/{object-namespace}/{classes, traits, or interfaces}/{project-object-slug}/{methods or properties} 这是所有用于单个类（Class）、特性（Trait）或接口（Interface）的方法或属性项目对象的页面列表的前缀URL。

性能

文档器旨在仅在绝对必要的情况下实例化或计算（懒加载）。文档器旨在在对象和值实例化或计算后保持对它们（缓存）。

文档器尚未进行性能测试；如果实际应用中的性能成为明显问题，我们将进行测试。话虽如此，预计文档器中最耗时的操作将是设置项目初始文件数组。

8fold / php-documenter

维护者

详细信息

README

设置

初始化

元素、对象和符号

文档块

路由

性能