documentation

[azjezz]

current documentation is mostly useless, as the same could be achieved by simply browsing through src/Psl directory.

Plan:

• write better documentation using markdown
• each component should be documented on it's own, with examples.
• each component documentation should include all symbols defined within the component.
• deploy documentation using GitHub pages.

---

Task list:

• [ ] Cover
• [x] Installation
• [ ] Contribution
• [ ] Components
  • [x] Async
  • [x] Channel
  • [x] Class
  • [ ] Collection
  • [ ] DataStructure
  • [ ] Dict
  • [ ] Encoding
    • [ ] Base64
    • [ ] Hex
  • [ ] Env
  • [ ] File
  • [ ] Filesystem
  • [x] Fun
  • [ ] Hash
  • [x] Html
  • [ ] IO
  • [x] Interface
  • [x] Iter
  • [x] Json
  • [x] Math
  • [ ] Network
  • [ ] Observer
  • [ ] Password
  • [x] Promise
  • [x] PseudoRandom
  • [ ] RandomSequence
  • [ ] Regex
  • [ ] Result
  • [x] Runtime
  • [x] SecureRandom
  • [x] Shell
  • [ ] Str
    • [ ] Byte
    • [ ] Grapheme
  • [x] TCP
  • [x] Trait
  • [ ] Type
  • [x] Unix
  • [ ] Vec
• [ ] CHANGELOG
• [ ] Credits
• [ ] License

[azjezz]

documentation repository: https://github.com/php-standard-library/php-standard-library.github.io documentation url: https://php-standard-library.github.io

[azjezz]

channel component documentation has been written 🎉 https://php-standard-library.github.io/#/components/channel/

[azjezz]

class, interface, trait, and html components are now documented 🎉

https://php-standard-library.github.io/#/components/class/ https://php-standard-library.github.io/#/components/interface/ https://php-standard-library.github.io/#/components/trait/ https://php-standard-library.github.io/#/components/html/

[azjezz]

shell component is now documented:

https://php-standard-library.github.io/#/components/shell/

[veewee]

Been through the links above: very clear explanations. Haven't really found any typos at this point either 🙂

[azjezz]

pseudo-random, and secure-random components are now documented:

https://php-standard-library.github.io/#/components/pseudo-random/ https://php-standard-library.github.io/#/components/secure-random/

[azjezz]

runtime component is now documented:

https://php-standard-library.github.io/#/components/runtime/

[azjezz]

shell exceptions are now documented:

https://php-standard-library.github.io/#/components/shell/?id=exceptions

[azjezz]

@veewee wanna take care of Fun and Regex? i think you would be better at explaining those.

[azjezz]

json component is now documented:

https://php-standard-library.github.io/#/components/json/

[azjezz]

iter component is now documented:

https://php-standard-library.github.io/#/components/iter/

[veewee]

@veewee wanna take care of Fun and Regex? i think you would be better at explaining those.

I don't mind, but am a bit limited in OS time the coming 2 months. We're working hard on a tight deadline.

Fyi : Gonna mark every page I proof-read with an emoji to keep track :)

[azjezz]

I just added inline-code-highlight docsify plugin to the documentation.

This helps 99% of the time, and makes things more readable, e.g:

examples of before/after

Html before:

Html after:

Shell before:

Shell after:

However, a big disadvantage is that it breaks for signatures such as Iter\apply<T>(iterable<T> $iterable, (callable(T): void) $callback): void;

everything gets highlighted correctly, except the Ìter\apply<T> part:

so to get around this, i moved the generic templates declaration before the function name, so now it looks like this:

It looks a bit weird, but works, and it's the only option i could come up with at the time.

personally, i don't see it as an issue since before signatures are not real, but rather put in place to help people understand the function behavior.

If anyone has a better option, I'm open for suggestions.

commit: https://github.com/php-standard-library/php-standard-library.github.io/commit/c40c7299df4f4640fc52ff669c217d97eb8db370

[veewee]

Would it make sense to introduce an attribute for annotating the generics in the docs? It might be less confusing for PHP developers?

[azjezz]

couple of solutions:

[azjezz]

i think @template works great.

i also did some modification to remove list style type, and add a bottom border for each symbol definition.

before:

after:

[azjezz]

another update:

each symbol now has a border around it to make it look like a box, the next step would be to give these "boxes" unique ids, and add a "link" button, so people can share links to a specific symbol in the documentation.

[veewee]

Yes, @template works well indeed. Would it also make sense to add @pure instead of showing it in those separate info elements?

[azjezz]

yea, i think that would work, same for @mutation-free, @external-mutation-free, and @immutable

[azjezz]

done 🎉

[azjezz]

async component is now documented:

https://php-standard-library.github.io/#/components/async/

[VincentLanglet]

HI @azjezz, I think it could be useful to add some documentation about why using this library (or maybe I missed it). For instance, I saw a PR https://github.com/Roave/BackwardCompatibilityCheck/pull/306 removing some libraries in favor of this one, and I was kinda curious about why this change was worth it.

So for instance, as a developper using webmozart/assert currently, would I have some benefit to change ?

[azjezz]

I think that would be a nice addition, but currently it's not a high priority, as it's more important to document components then writing a comparison.

[azjezz]

fun, and promise components are now documented:

https://php-standard-library.github.io/#/components/promise/ https://php-standard-library.github.io/#/components/fun/

[azjezz]

TCP component is now documented:

https://php-standard-library.github.io/#/components/tcp/

[azjezz]

Unix component is now documented:

https://php-standard-library.github.io/#/components/unix/

[veewee]

Fyi : The docs web site on my phone tries to display the content in about half the available screen size. It is due to the borders and the margins. It is a bit annoying, not sure if other people will read it on the phone though 😉

[azjezz]

Yea, I'm aware of that issue, i will try fixing it after finishing up the documentation ( though, I am not really good with CSS stuff :p )