xlient/doc-php

一个用于从PHPDoc注释和反射生成Markdown文件的PHP库。

维护者

详细信息

github.com/xlientrc/xlient-doc-php

主页

源代码

问题

安装: 12

依赖项: 0

建议者: 0

安全: 0

星标: 1

关注者: 1

分支: 0

公开问题: 0

dev-main / 1.0.x-dev 2023-08-07 03:16 UTC

Requires

Requires (Dev)

Unlicense ad55d352548e43feb3debb61be53a6e6a0f2b9cc

documentationphpdocmarkdownxlient

This package is auto-updated.

Last update: 2024-09-07 05:52:17 UTC

README

此库是一个PHP文档生成器，用于生成与GitHub兼容的Markdown格式的PHP代码文档。

需要PHP 8.1或更高版本。

安装

composer require xlient/doc-php

配置

您希望生成文档的任何PHP文件都必须已经加载或可自动加载。

建议使用composer安装它们，然后指向位于/vendor中的包文件夹的srcDir参数。

use Xlient\Doc\Php\Configuration;
use Xlient\Doc\Php\PhpDocumentor;

use const DIRECTORY_SEPARATOR as DS;

// Set current working directory to composer.json directory.
chdir(dirname(__DIR__));

// Include composer autoload file.
require_once getcwd() . DS . 'vendor' . DS . 'autoload.php';

// Configure the documentor.
$config = new Configuration(...);

// Instanciate the documentor.
$documentor = new PhpDocumentor(
    srcDirs: [
        getcwd() . '/vendor/package/name1/src',
        getcwd() . '/vendor/package/name2/src',
    ],
    destDir: getcwd() . '/docs',
    config: $config,
);

// Generate the documentation files.
$files = $documentor->make();

配置

所有配置均使用Configuration类设置。

Configuration类__construct方法的参数顺序在版本之间可能不保证一致。因此，建议使用命名参数。

$config = new Configuration(
    baseNamespaces: [
        '\\Xlient'
    ],
    basePaths [
        '\\Xlient' => 'xlient'
    ],
    ...
);

baseNamespaces

只有这些命名空间内的文件会被文档化。

创建目录时，此命名空间的等效目录路径将从路径开头删除。

默认值

baseNamespace: [],

示例

baseNamespace: [
    '\\Xlient'
],

使用baseNamespace: ['\\Xlient']，结果目录路径\\Xlient\\Doc\\Php将变为/doc/php。

basePaths

这些路径将添加到任何生成的相对文档文件路径的开头。

数组键是命名空间，值是对应的路径。

默认值

basePaths: [],

示例

basePaths: [
    '\\Xlient' => '/help'
],

使用basePaths: ['\\Xlient' => '/help']，结果路径\\Xlient\\Doc\\Php\Configuration将变为{destDir}/help/doc/php/configuration.md

baseUrls

此URL将添加到匹配基础命名空间的任何URL路径的开头。

数组键是要匹配的命名空间，值是对应的URL。

默认值

baseUrls: [],

示例

baseUrls: [
    '\\Xlient' => 'https://xlient.com'
],

pathFixes

一组键值对，用于覆盖默认的路径名称生成。

默认情况下，命名空间将根据大小写拆分。因此，MyName将变为my-name。

这并不总是期望的结果，因此此选项允许您将命名空间值修改为替代值。

默认值

pathFixes: [],

示例

pathFixes: [
    'MyName' => 'myname'
],

namespaceUrls

一组URL，用于链接到基础命名空间之外的项目。

{php_doc}将被替换为php.net风格的文档路径。

对于\\Random\\Engine\\Secure，生成的文件名将是class.random-engine-secure.php

默认值

namespaceUrls: [
    '\\' => 'https://php.ac.cn/manual/en/{php_doc}',
    '\\Random\\' => 'https://php.ac.cn/manual/en/{php_doc}',
    '\\Psr\\' => 'https://www.php-fig.org',
    '\\Psr\\Cache\\' => 'https://www.php-fig.org/psr/psr-6',
    '\\Psr\\Clock\\' => 'https://www.php-fig.org/psr/psr-20',
    '\\Psr\\Container\\' => 'https://www.php-fig.org/psr/psr-11',
    '\\Psr\\EventDispatcher\\' => 'https://www.php-fig.org/psr/psr-14',
    '\\Psr\\Http\\Client\\' => 'https://www.php-fig.org/psr/psr-18',
    '\\Psr\\Http\\Message\\RequestFactoryInterface' => 'https://www.php-fig.org/psr/psr-17',
    '\\Psr\\Http\\Message\\ResponseFactoryInterface' => 'https://www.php-fig.org/psr/psr-17',
    '\\Psr\\Http\\Message\\ServerRequestFactoryInterface' => 'https://www.php-fig.org/psr/psr-17',
    '\\Psr\\Http\\Message\\StreamFactoryInterface' => 'https://www.php-fig.org/psr/psr-17',
    '\\Psr\\Http\\Message\\UploadedFileFactoryInterface' => 'https://www.php-fig.org/psr/psr-17',
    '\\Psr\\Http\\Message\\UriFactoryInterface' => 'https://www.php-fig.org/psr/psr-17',
    '\\Psr\\Http\\Message\\' => 'https://www.php-fig.org/psr/psr-7',
    '\\Psr\\Http\\Server\\' => 'https://www.php-fig.org/psr/psr-15',
    '\\Psr\\Link\\' => 'https://www.php-fig.org/psr/psr-13',
    '\\Psr\\Log\\' => 'https://www.php-fig.org/psr/psr-3',
    '\\Psr\\SimpleCache\\' => 'https://www.php-fig.org/psr/psr-16',
],

配置中设置的任何namespaceUrls都将与默认值合并。

urlCallback

提供外部URL的更精确方法。

默认值

urlCallback: null,

示例

$url将包含任何匹配的namespaceUrls值或null如果没有匹配。

urlCallback: function(string $name, ?string $url): ?string {
    if (str_starts_with($name, '\\Psr\\')) {
        $url = 'https://www.php-fig.org';
    }

    return $url;
},

methodUrlCallback

提供外部URL以供外部类方法使用的方法。

默认值

methodUrlCallback: null,

示例

methodUrlCallback: function(string $class, string $method): ?string {
    $url = null;
    // ...
    return $url;
},

classPublic

当为true时，包括公共类项。

默认值

classPublic: true,

classProtected

当为true时，包括受保护的类项。

默认值

classProtected: true,

classPrivate

当为true时，包括私有类项。

默认值

classPrivate: true,

classSeparator

用于在继承列表中分隔类名的一串字符。

默认值

classSeparator: ' » ',

methodFiles

当为true时，将为每个类方法生成单独的文件。

默认值

methodFiles: true,

functionFiles

当为true时，将为每个函数生成单独的文件。

functionFiles: true,

functionDir

当为true时，函数文件将放置在与函数文件同名的子目录中。

functionDir: true,

classFilenamePrefix

用于前缀类文档文件名的一个值。

默认值

classFilenamePrefix: '',

示例

classFilenamePrefix: 'class-',

classFilenameSuffix

用于后缀类文档文件名的一个值。

默认值

classFilenameSuffix : '',

enumFilenamePrefix

用于前缀枚举文档文件名的一个值。

默认值

enumFilenamePrefix : '',

enumFilenameSuffix

用于后缀枚举文档文件名的一个值。

默认值

enumFilenameSuffix : '',

interfaceFilenamePrefix

用于接口文档文件名的前置值。

默认值

interfaceFilenamePrefix : '',

interfaceFilenameSuffix

用于接口文档文件名的后置值。

默认值

interfaceFilenameSuffix : '',

traitFilenamePrefix

用于特性文档文件名的前置值。

默认值

traitFilenamePrefix : '',

traitFilenameSuffix

用于特性文档文件名的后置值。

默认值

traitFilenameSuffix : '',

methodFilenamePrefix

用于方法文档文件名的前置值。

默认值

methodFilenamePrefix : '',

methodFilenameSuffix

用于方法文档文件名的后置值。

默认值

methodFilenameSuffix : '',

functionFilenamePrefix

用于函数文档文件名的前置值。

默认值

functionFilenamePrefix : '',

functionFilenameSuffix

用于函数文档文件名的后置值。

默认值

functionFilenameSuffix : '',

constantsFilename

用于常量文档文件的文件名。

默认值

constantsFilename : 'constants',

functionsFilename

用于函数文档文件的文件名。

默认值

functionsFilename : 'functions',

classPathPrefix

用于类文档目录名的前置值。

默认值

classPathPrefix: '',

示例

classPathPrefix: 'class-',

classPathSuffix

用于类文档目录名的后置值。

默认值

classPathSuffix : '',

enumPathPrefix

用于枚举文档目录名的前置值。

默认值

enumPathPrefix : '',

enumPathSuffix

用于枚举文档目录名的后置值。

默认值

enumPathSuffix : '',

interfacePathPrefix

用于接口文档目录名的前置值。

默认值

interfacePathPrefix : '',

interfacePathSuffix

用于接口文档目录名的后置值。

默认值

interfacePathSuffix : '',

traitPathPrefix

用于特性文档目录名的前置值。

默认值

traitPathPrefix : '',

traitPathSuffix

用于特性文档目录名的后置值。

默认值

traitPathSuffix : '',

labels

用于文档标签的关键值对数组。

默认值

labels: [
    'class' => 'Class',
    'extends' => 'Extends',
    'implements' => 'Implements',
    'uses' => 'Uses',
    'class_synopsis' => 'Class Synopsis',
    'constructor' => 'Constructor',
    'cases' => 'Cases',
    'case_details' => 'Case Details',
    'constants' => 'Constants',
    'constant_synopsis' => 'Constant Synopsis',
    'constant_details' => 'Constant Details',
    'properties' => 'Properties',
    'property_details' => 'Property Details',
    'methods' => 'Methods',
    'method_details' => 'Method Details',
    'functions' => 'Functions',
    'function_synopsis' => 'Function Synopsis',
    'function_details' => 'Function Details',
    'public' => 'Public',
    'protected' => 'Protected',
    'private' => 'Private',
    'name' => 'Name',
    'value' => 'Value',
    'type' => 'Type',
    'description' => 'Description',
    'returns' => 'Returns',
    'throws' => 'Throws',
    'deprecated' => 'Deprecated',
    'internal' => 'Internal',
    'generated' => 'Generated',
],

配置中设置的任何 labels 将与默认值合并。

makeClassDescription

当为 true 时，类文档将包括类的描述。

默认值

makeClassDescription: true,

makeClassExtends

当为 true 时，类文档将包括父类列表。

默认值

makeClassExtends: true,

makeClassImplements

当为 true 时，类文档将包括实现的接口列表。

默认值

makeClassImplements: true,

makeClassUses

当为 true 时，类文档将包括类使用的特性列表。

默认值

makeClassUses: true,

makeClassConstructor

当为 true 时，类构造函数将在文档文件中有自己的部分。

默认值

makeClassConstructor: true,

makeClassSynopsis

当为 true 时，将生成类似 php.net 风格的类索引。

默认值

makeClassSynopsis: true,

makeClassCases

当为 true 时，任何枚举中的 case 语句都将被文档化。

默认值

makeClassCases: true,

makeClassCaseDetails

当为 true 时，枚举中每个 case 的更详细概述将被文档化。

默认值

makeClassCaseDetails: true,

makeClassConstants

当为 true 时，类中的任何常量都将被文档化。

默认值

makeClassConstants: true,

makeClassConstantDetails

当为 true 时，类中每个常量的更详细概述将被文档化。

默认值

makeClassConstantDetails: true,

makeClassProperties

当为 true 时，类中的任何属性都将被文档化。

默认值

makeClassProperties: true,

makeClassPropertyDetails

当为 true 时，类中每个属性的更详细概述将被文档化。

默认值

makeClassPropertyDetails: true,

makeClassMethods

当为 true 时，类中的任何方法都将被文档化。

默认值

makeClassMethods: true,

makeClassMethodDetails

当为 true 时，类中每个方法的更详细概述将被文档化。

默认值

makeClassMethodDetails: true,

makeConstants

当为 true 时，任何命名空间直接子级的常量都将被文档化。

默认值

makeConstants: true,

makeConstantsDescription

当为 true 时，常量文档将包括每个常量的描述。

默认值

makeConstantsDescription: true,

makeConstantSynopsis

当为 true 时，将生成常量的 PHP 代码概要。

默认值

makeConstantSynopsis: true,

makeConstantDetails

当为 true 时，每个常量的更详细概述将被文档化。

默认值

makeConstantDetails: true,

makeDefines

当为 true 时，使用 define 函数定义的常量将被包括在常量文档中。

默认值

makeDefines: true,

makeFunctions

当为 true 时，任何命名空间直接子级的函数都将被文档化。

默认值

makeFunctions: true,

makeFunctionsDescription

当为 true 时，函数文档将为每个函数提供描述。

默认值

makeFunctionsDescription: true,

makeFunctionSynopsis

当为真时，将生成函数的PHP代码概要。

默认值

makeFunctionSynopsis: true,

makeFunctionDetails

当为真时，将记录每个函数的更详细概览。

默认值

makeFunctionDetails: true,

makeSynopsisMeta

当为真时，将生成包含概要URL元数据的JSON元文件，以便在代码高亮后注入链接。

默认值

makeSynopsisMeta: true,

showDeprecated

当为真时，将包括在文档中的已弃用项。

默认值

showDeprecated: true,

showDeprecatedLabel

当为真时，在文档中已弃用项下将出现一个弃用标签。

默认值

showDeprecatedLabel: true,

showInternal

当为真时，将包括在文档中的内部项。

默认值

showInternal: true,

showInternalLabel

当为真时，在文档中的内部项下将出现一个内部标签。

默认值

showInternalLabel: true,

showGenerated

当为真时，将包括在文档中的生成项。

默认值

showGenerated: true,

showGeneratedLabel

当为真时，在文档中的生成项下将出现一个生成标签。

默认值

showGeneratedLabel: true,

accessModifierOrder

一个PHP访问修饰符数组，按其出现的顺序。

默认值

use Xlient\Php\Doc\PhpAccessModifier;
//...
accessModifierOrder: [
    PhpAccessModifier::PUBLIC,
    PhpAccessModifier::PROTECTED,
    PhpAccessModifier::PRIVATE,
],

typeOrder

一个PHP类型数组，按其出现的顺序。

默认值

use Xlient\Php\Doc\PhpType;
//...
typeOrder: [
    PhpType::NULL,
    PhpType::BOOL,
    PhpType::TRUE,
    PhpType::FALSE,
    PhpType::INT,
    PhpType::FLOAT,
    PhpType::STRING,
    PhpType::ARRAY,
    PhpType::ITERABLE,
    PhpType::CALLABLE,
    PhpType::OBJECT,
    PhpType::CLASS_NAME,
    PhpType::VOID,
    PhpType::SELF,
    PhpType::STATIC,
    PhpType::NEVER,
],

sortByName

当为真时，项将按名称排序。

默认值

sortByName: true,

sortByAccessModifier

当为真时，项将按指定的accessModifierOrder顺序排序。

默认值

sortByAccessModifier: true,

groupByAccessModifier

当为真时，项将按访问修饰符分组。

默认值

groupByAccessModifier: true,

sortByType

当为真时，类型将按指定的typeOrder顺序排序。

默认值

sortByType: true,

inheritDocComments

当为真时，子类的PHPDoc注释将继承其相应父PHPDoc注释中缺失的信息。

@inheritDoc和{@inheritDoc}也将相应处理。

@inheritdoc / @inheritDoc

将继承整个父PHPDoc注释。

{@inheritdoc} / {@inheritDoc}

将只继承描述并按标准内联。

如果它是PHPDoc注释中唯一的文本/标签，则将继承整个父PHPDoc注释。这不符合标准，但许多代码以这种方式使用{@inheritdoc}。

默认值

inheritDocComments: true,

prioritizeDocComments

当为真时，PHPDoc注释中的信息将优先于从反射中获得的信息。

默认值

prioritizeDocComments: true,

escapeDocComments

当为真时，PHPDoc注释文本将被转义以避免干扰Markdown。

默认值

escapeDocComments = false,

useNullableSyntax

当为真时，在适当的位置将使用?而不是null。

默认值

useNullableSyntax: true,

enableTables

当为真时，某些信息将放在表格中而不是更友好的标题和段落中。

默认值

enableTables: true,

indentLength

缩进代码的空间长度。

默认值

indentLength: 4,

lineLength

代码行的最大字符长度。

默认值

lineLength: 80,

override

当为真时，在制作之前将删除destDir中现有的任何生成的文档。

默认值

override = false,