README

免责声明/警告

这还是一个正在进行中的项目。代码已经可以工作（在另一个上下文中），但我对依赖项发布游戏还不熟悉。所以我还在尝试弄清楚东西，并不得不先发布它，以便测试。

介绍

此包从特定的注释自动生成文档。

问题1：功能分散

事实确实在代码中，但代码通常分散在许多文件和文件夹中。一个业务逻辑特征可能基于代码中的不同区域。如果使用难以追踪的代码，例如动态调用类、方法或属性，这会特别成问题。

在这些情况下，理解组件的最简单方法是要求架构师解释它。在这样做的时候，他们可以跨不同的文件，简要地说明在哪些地方发生了什么。

问题2：过时或被忽视的文档

文档是工作，通常与上下文切换相关联，并且往往是过时的。如果没有一个好的系统，很难找到当前正在工作的区域的文档。

解决方案

为了解决这些问题，这个库使用注释来自动生成最新的文档，并以吸引人的格式展示在一个地方。它是从代码中分散的各个部分中提取的。文档发生在代码发生的地方。这使得开发者可以让文档成为他们编码工作的一部分，而无需切换上下文。

要求

为使用在Symfony 5.2中构建，与其他软件的兼容性不确定。
要求所有分析的PHP文件都遵循PSR4规范。特别是规范3.3“终止类的名称对应于以.php结尾的文件名。文件名必须与终止类的名称匹配大小写。”（见https://www.php-fig.org/psr/psr-4/#2-specification）

安装

步骤1：使用Composer安装包

composer require steveolotu/featuredocu

步骤2：将包添加到您的bundles.php文件中

// config/bundles.php
return [
//..
SteveOlotu\FeatureDocu\FeatureDocuBundle::class => ['all' => true],
];

(可选) 注册Twig模板

要使用Twig模板，需要先注册路径。

为此，将路径添加到文件：config/packages/twig.yaml。

如果变量“paths”尚不存在，则创建它，并添加默认路径

之前

twig:
    ...
    default_path: '%kernel.project_dir%/templates'
    ...

之后

twig:
    ...
    default_path: '%kernel.project_dir%/templates'
    paths:
        - '%kernel.project_dir%/templates'
        - '%kernel.project_dir%/vendor/steveolotu/featuredocu/templates'
    ...

使用方法

添加引用

将一个或多个@FeatureDocuAnnotation注释添加到任何类、方法或属性中。

必需参数包括

identifier：功能的名称。建议使用斜杠分隔级别。
order：特定标识符条目的显示顺序。必须是唯一的。提示：使用100的步长允许在不更新所有相关引用的情况下添加元素。
Description：解释特定类、方法或属性在功能中的部分的文本。

示例

@FeatureDocuAnnotation(identifier="Backup/generate", order="1000", description="UI starting point")

@FeatureDocuAnnotation(identifier="Backup/delete", order="1040", description="UI starting point.")

使用引用

要生成输出，需要三个步骤

使用您希望的道路初始化对象

$featureDocu = new FeatureDocu($path, $reader, $twig);

分析输出检查指定路径中的文件

$featureDocu->analyze();

生成输出。

输出引用

数组

$featureDocu->getOutputArray();

Html：一个HTML表格

$featureDocu->getOutputHtml();

输出一个“目录”列表的标识符

假设存在几个具有两个标识符 backup/create 和 backup/delete 的引用。

数组：功能列表

以下代码

$featureDocu->getFeatureListNestedArray();

...将生成以下格式的数组

['backup' => [
    ['create' => true],
    ['delete' => true],
]

注意：值 "true" 仅作为占位符。有用的数据存储在键中。

HTML：一个分层缩进和编号的列表

以下代码

$featureDocu->getFeatureListHtmlList();

...将生成嵌套的 <ul> HTML 列表

1 backup
 1.1 create
 1.2 delete

注意：最低级别的条目（代表实际标识符，此处为 create 和 backup）是 HTML 参考表中的部分链接（需要在同一页面上，以便连接能够工作）。

内部使用的输出格式

ListListObject：用于收集信息的内部对象。

$featureDocu->getListObject();

要获取在分析代码后文件中找到的所有类对象，请使用

$featureDocu->getClasses();

待办事项#

添加一些测试
需求不确定，请检查
检查代码风格
检查未使用的代码

贡献者

特别感谢 eFrane。

steveolotu / featuredocu

维护者

详细信息