danog/endtoend-test-psl
1
0
Fork 0
mirror of https://github.com/danog/endtoend-test-psl.git synced 2025-01-22 21:31:25 +01:00
Code Issues Packages Projects Releases Wiki Activity

improve symbol links in documentation

Browse Source
This commit is contained in:
azjezz 2021-03-17 02:13:15 +01:00
parent 978de7b7a6
commit 96cf513172
3 changed files with 594 additions and 569 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1058
docs/README.md
View File

File diff suppressed because it is too large Load Diff

93
docs/documenter.php
View File

@ -93,41 +93,36 @@ function get_namespace_documentation(string $namespace): string
$lines[] = '';
/**
* @param array{
* 'constants' => list<string>,
* 'functions' => list<string>,
* 'interface' => list<string>,
* 'classes' => list<string>,
* 'traits' => list<string>,
* } $symbols
* @param 'constants'|'functions'|'interfaces'|'classes'|'traits' $type
* @param array<int, list<string>> $symbols
*
* @return list<string>
*/
$generator = static function (
string $directory,
array $symbols,
string $type
int $type
): array {
$lines = [];
if (Iter\count($symbols[$type]) > 0) {
$lines[] = Str\format('#### `%s`', Str\uppercase($type));
$lines[] = Str\format('#### `%s`', get_symbol_type_name($type));
$lines[] = '';
foreach ($symbols[$type] as $function) {
$short_name = Str\after_last($function, '\\');
if ('constants' === $type) {
$url = Str\format('%s%s%s.php', $directory, Filesystem\SEPARATOR, 'constants');
foreach ($symbols[$type] as $symbol) {
$symbol_short_name = Str\after_last($symbol, '\\');
if (Loader::TYPE_CONSTANTS === $type) {
$symbol_file = Str\format('%s%s%s.php', $directory, Filesystem\SEPARATOR, 'constants');
} else {
$url = Str\format('%s%s%s.php', $directory, Filesystem\SEPARATOR, $short_name);
$symbol_file = Str\format('%s%s%s.php', $directory, Filesystem\SEPARATOR, $symbol_short_name);
}
$symbol_file_contents = Filesystem\read_file(Filesystem\canonicalize(__DIR__ . '/' . $symbol_file));
$deprecation_notice = '';
if (Str\contains(Filesystem\read_file(Filesystem\canonicalize(__DIR__ . '/' . $url)), '@deprecated')) {
if (Str\contains($symbol_file_contents, '@deprecated')) {
$deprecation_notice .= ' ( deprecated )';
}
$lines[] = Str\format('- [%s](%s)%s', $short_name, $url, $deprecation_notice);
$definition_line = get_symbol_definition_line($symbol, $type);
$lines[] = Str\format('- [%s](%s#L%d)%s', $symbol_short_name, $symbol_file, $definition_line, $deprecation_notice);
}
$lines[] = '';
@ -141,11 +136,11 @@ function get_namespace_documentation(string $namespace): string
return Str\join(Vec\concat(
$lines,
$generator($directory, $symbols, 'constants'),
$generator($directory, $symbols, 'functions'),
$generator($directory, $symbols, 'interfaces'),
$generator($directory, $symbols, 'classes'),
$generator($directory, $symbols, 'traits'),
$generator($directory, $symbols, Loader::TYPE_CONSTANTS),
$generator($directory, $symbols, Loader::TYPE_FUNCTION),
$generator($directory, $symbols, Loader::TYPE_INTERFACE),
$generator($directory, $symbols, Loader::TYPE_CLASS),
$generator($directory, $symbols, Loader::TYPE_TRAIT),
['']
), "\n");
}
@ -153,13 +148,7 @@ function get_namespace_documentation(string $namespace): string
/**
* Return a shape contains all direct symbols in the given namespace.
*
* @return array{
* 'constants' => list<string>,
* 'functions' => list<string>,
* 'interface' => list<string>,
* 'classes' => list<string>,
* 'traits' => list<string>,
* }
* @return array<int, list<string>>
*/
function get_direct_namespace_symbols(string $namespace): array
{
@ -179,11 +168,11 @@ function get_direct_namespace_symbols(string $namespace): array
);
return [
'constants' => $filter(Loader::CONSTANTS),
'functions' => $filter(Loader::FUNCTIONS),
'interfaces' => $filter(Loader::INTERFACES),
'classes' => $filter(Loader::CLASSES),
'traits' => $filter(Loader::TRAITS),
Loader::TYPE_CONSTANTS => $filter(Loader::CONSTANTS),
Loader::TYPE_FUNCTION => $filter(Loader::FUNCTIONS),
Loader::TYPE_INTERFACE => $filter(Loader::INTERFACES),
Loader::TYPE_CLASS => $filter(Loader::CLASSES),
Loader::TYPE_TRAIT => $filter(Loader::TRAITS),
];
}
@ -222,3 +211,39 @@ function get_all_namespaces(): array
'Psl\Vec',
];
}
/**
* Return the name of the symbol type.
*/
function get_symbol_type_name(int $type): string {
switch ($type) {
case Loader::TYPE_CONSTANTS:
return 'Constants';
case Loader::TYPE_FUNCTION:
return 'Functions';
case Loader::TYPE_INTERFACE:
return 'Interfaces';
case Loader::TYPE_CLASS:
return 'Classes';
case Loader::TYPE_TRAIT:
return 'Traits';
}
}
/**
* Return the line where $symbol is defined.
*/
function get_symbol_definition_line(string $symbol, int $type): int
{
if (Loader::TYPE_CONSTANTS === $type) {
return 0;
}
if (Loader::TYPE_FUNCTION === $type) {
$reflection = new ReflectionFunction($symbol);
} else {
$reflection = new ReflectionClass($symbol);
}
return $reflection->getStartLine();
}

12
src/Psl/Internal/Loader.php
View File

@ -599,17 +599,17 @@ final class Loader
'Psl\Filesystem\Exception\RuntimeException',
];
private const TYPE_CONSTANTS = 1;
public const TYPE_CONSTANTS = 1;
private const TYPE_FUNCTION = 2;
public const TYPE_FUNCTION = 2;
private const TYPE_INTERFACE = 4;
public const TYPE_INTERFACE = 4;
private const TYPE_TRAIT = 8;
public const TYPE_TRAIT = 8;
private const TYPE_CLASS = 16;
public const TYPE_CLASS = 16;
private const TYPE_CLASSISH = self::TYPE_INTERFACE | self::TYPE_TRAIT | self::TYPE_CLASS;
public const TYPE_CLASSISH = self::TYPE_INTERFACE | self::TYPE_TRAIT | self::TYPE_CLASS;
private function __construct()
{