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
• Installation
• Contribution
• Components
  • Async
  • Channel
  • Class
  • Collection
  • DataStructure
  • Dict
  • Encoding
    • Base64
    • Hex
  • Env
  • File
  • Filesystem
  • Fun
  • Hash
  • Html
  • IO
  • Interface
  • Iter
  • Json
  • Math
  • Network
  • Observer
  • Password
  • Promise
  • PseudoRandom
  • RandomSequence
  • Regex
  • Result
  • Runtime
  • SecureRandom
  • Shell
  • Str
    • Byte
    • Grapheme
  • TCP
  • Trait
  • Type
  • 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: php-standard-library/php-standard-library.github.io@c40c729

[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 Roave/BackwardCompatibilityCheck#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 )