Comments (5)
do we have an example on how documentation files should look like ?
does this example help Arr
from psl.
I don't have an example in mind, but one thing to note is that we want to document generic functions, so instead of:
function at(array $array, $key)
it would be:
function at<Tk as array-key, Tv>(array<Tk, Tv> $array, Tk $key): Tv
as that's how the function would look like if PHP had generics, but currently we use Psalm for that.
Note, when using generics in code, i would recommand using hack
as a language instead of php, so we get a better highlight for generics.
example:
the following results in broken highlighting:
```php
function at<Tk of array-key, Tv>(array<Tk, Tv> $array, Tk $key): Tv
```
this works as Hack syntax is similar to PHP and it supports generics.
```hack
function at<Tk of array-key, Tv>(array<Tk, Tv> $array, Tk $key): Tv
```
Another thing is that there's no need to have a folder for each version, as once we are done with 1.0
, we would make another branch for that.
the ideal structure for the files would be something like this:
docs/
README.md // <-- general docs about what PSL is .. etc
installation.md // document how to install PSL and use it, also how to preload PSL.
str/
README.md // <-- general documentation of the Str component
constants.md // <-- document all constants in that comonent ( usually they are in a constants.php file )
function/
replace.md // <-- document the `Str\replace` function
replace_ci.md // <-- document the `Str\replace_ci`
...
class/
someclass.php
interface/
someinterface.php
so that every component can have its own folder, with a readme.md, in that readme we would also list all functions/classes of that component, with links to their documentation ( docs/str/README.md ):
example:
# Str
<-- documentation -->
## constants
- [`Psl\Str\FOO`](constants.md)
- [`Psl\Str\BAR`](constants.md)
## functions
- [`Psl\Str\replace`](function/replace.function.md)
- [`Psl\Str\replace_ci`](function/replace_ci.md)
...
## interfaces
- [`Psl\Str\SomeInterface`](interface/someinterface.md)
## classes
- [`Psl\Str\SomeClass`](class/someclass.md)
## traits
- [`Psl\Str\SomeTrait`](trait/sometrait.md)
from psl.
by the way, I would suggest documenting 1 component at the time and sending a PR for that instead of trying to document everything together, so it makes things easier to review, and we can focus on one thing at the time.
from psl.
Currently the code also contains detailed docblocks with code samples in various places.
I don't really know of any tooling, but would generating the docs from code make sense instead of manually keeping docs and code in sync?
from psl.
I have actually tried to do that in the past but gave up on it.
this is the generated I previously wrote ( a bit messy and incomplete ):
<?php
declare(strict_types=1);
namespace Local;
use Psl\{Arr, Str};
use Roave\BetterReflection\BetterReflection;
use Roave\BetterReflection\Reflection\ReflectionClass;
use Roave\BetterReflection\Reflection\ReflectionConstant;
use Roave\BetterReflection\Reflection\ReflectionFunction;
use Roave\BetterReflection\Reflector\ConstantReflector;
use Roave\BetterReflection\SourceLocator\Type\SingleFileSourceLocator;
use RuntimeException;
require_once __DIR__ . '/../vendor/autoload.php';
$symbols = [];
$symbols['constants'] = get_defined_constants();
$symbols['functions'] = get_defined_functions()['user'];
$symbols['classes'] = get_declared_classes();
$symbols['interfaces'] = get_declared_interfaces();
$symbols['traits'] = get_declared_traits();
$extract_component = static function (string $type): ?string {
if (!Str\starts_with($type, 'Psl\\')) {
return null;
}
if (Str\contains($type, 'Internal')) {
return null;
}
$name = Str\slice($type, Str\search_last($type, '\\') + 1);
$component = Str\strip_suffix($type, Str\concat('\\', $name));
$component = Str\strip_prefix($component, 'Psl\\');
return $component;
};
$fix_function_casing = static function (string $function): string {
$parts = Str\split($function, '\\');
$parts = Arr\map($parts, fn(string $part) => Str\capitalize($part));
$parts[Arr\last_key($parts)] = Str\lowercase(Arr\last($parts));
return Str\join($parts, '\\');
};
/**
* @psalm-var array<string, array{
* constants: list<string>,
* functions: list<string>,
* classes: list<string>,
* interfaces: list<string>,
* traits: list<string>
* }> $components
*/
$components = [];
foreach ($symbols['constants'] as $symbol => $value) {
$component = $extract_component($symbol);
if (null === $component) {
continue;
}
$components[$component]['constants'][] = $symbol;
}
foreach (['functions', 'classes', 'interfaces', 'traits'] as $type) {
foreach ($symbols[$type] as $symbol) {
if ('functions' === $type) {
$symbol = $fix_function_casing($symbol);
}
$component = $extract_component($symbol);
if (null === $component) {
continue;
}
$components[$component][$type][] = $symbol;
}
}
/**
* @param ReflectionConstant|ReflectionClass|ReflectionFunction $reflection
*/
$extract_docblock = static function($reflection): ?string {
$doc = $reflection->getDocComment();
$lines = Str\split(Str\trim($doc), "\n");
if (0 === Arr\count($lines) || (1 === Arr\count($lines) && Str\is_empty(Arr\first($lines)))) {
return null;
}
$lines = Arr\slice($lines, 1, Arr\count($lines) - 2);
$lines = Arr\map($lines, fn(string $line) => Str\strip_prefix($line, ' * '));
$lines = Arr\map($lines, fn(string $line) => Str\strip_prefix($line, ' *'));
$lines = Arr\filter($lines);
$lines = Arr\filter($lines, fn(string $line) => !Str\starts_with($line, '@'));
$lines = Arr\map($lines, static function(string $line): string {
if (Str\starts_with($line, ' ')) {
return Str\format(' %s', $line);
}
if (Str\ends_with($line, ':')) {
return Str\format(' %s%s', $line, "\n");
}
return Str\format(' %s', $line);
});
return Str\join($lines, "\n");
};
$generate_constants_documentation = static function(string $component, array $constants) use($extract_docblock): string {
$docs = <<<MARKDOWN
## Predefined Constants
The constants below are defined by the ${component} component of PSL.
MARKDOWN;
$br = (new BetterReflection());
$ref = new ConstantReflector(new SingleFileSourceLocator(
Str\format('%s/%s/constants.php', __DIR__.'/../src/Psl', $component),
$br->astLocator()
), $br->classReflector());
foreach ($constants as $constant) {
$reflection = $ref->reflect($constant);
$docblock = $extract_docblock($reflection);
$type = gettype(constant($constant));
$type = 'double' === $type ? 'float' : $type;
$nl = "\n";
if ($docblock) {
$nl .= <<<DOCS
${nl}${docblock}{$nl}{$nl}
DOCS;
}
$docs .= <<<DOCS
- *${constant}* ( ${type} )${nl}
DOCS;
}
return $docs;
};
$generate_documentation = static function(string $type, string $symbol): string {
die();
};
$mkdir = static function (string $directory): void {
if (!is_dir($directory) && !mkdir($directory) && !is_dir($directory)) {
throw new RuntimeException(sprintf('Directory "%s" was not created', $directory));
}
};
foreach($components as $component => $symbols) {
$directory = Str\format('%s/../docs/%s', __DIR__, Str\lowercase(Str\replace($component, '\\', '/')));
$mkdir($directory);
foreach ($symbols as $type => $list_of_symbols) {
if ('constants' === $type) {
$file = Str\format('%s/%s.md', $directory, $type);
$documentation = $generate_constants_documentation($component, $list_of_symbols);
file_put_contents($file, $documentation);
} else {
$sub_directory = Str\format('%s/%s', $directory, $type);
$mkdir($sub_directory);
continue;
foreach ($list_of_symbols as $symbol) {
$file = Str\format('%s/%s.md', $sub_directory, $symbol);
$documentation = $generate_documentation($type, $symbol);
file_put_contents($file, $documentation);
}
}
}
}
cc @lotfio if you want to do that, you can use the generator as a starting point.
from psl.
Related Issues (20)
- [Type] add `nonnull` type
- [Type] add `string_range` and `int_range` types.
- Undeprecate `positive_int` HOT 2
- base64 url safe encoding HOT 1
- Return value of `Psl\Str\trim()` must be of the type string, null returned HOT 6
- `CoercionException::withValue()` called but not throwed. Is this dead code? HOT 1
- Improve error messages for shape and vec -like types
- Improve Dict\merge HOT 1
- Make PSL PHPStan compliant
- Add an `option()` type to `Psl\Type` to coerce to a `Psl\Option\Option` HOT 3
- Split this package is multiple sub-packages HOT 2
- [Bug] Vec\range handles ints which don't roundtrip through floats wrong
- intersection + shapes unexpected behaviour (possible bug?) HOT 4
- Type\implements_interface HOT 3
- Corece an `array` out of an `stdClass`? HOT 3
- [RFC] Change `ResultInterface<T>` to `ResultInterface<T, E>` HOT 5
- chore: rename all enum cases to use PascalCase
- Improvement converted json type HOT 5
- Is nonnull helpful in any way? HOT 1
- PHPStan extension unable to report optional positive-int
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from psl.