Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

documentation #260

Open
18 of 46 tasks
azjezz opened this issue Nov 8, 2021 · 28 comments
Open
18 of 46 tasks

documentation #260

azjezz opened this issue Nov 8, 2021 · 28 comments
Assignees
Labels
Priority: High After critical issues are fixed, these should be dealt with before any further issues. Status: In Progress This issue is being worked on, and has someone assigned. Type: Documentation Updating documentation Type: Enhancement Most issues will probably ask for additions or changes.
Milestone

Comments

@azjezz
Copy link
Owner

azjezz commented Nov 8, 2021

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:

@azjezz azjezz added the Type: Enhancement Most issues will probably ask for additions or changes. label Nov 8, 2021
@azjezz azjezz added this to the 2.0.0 milestone Nov 8, 2021
@azjezz azjezz self-assigned this Nov 8, 2021
@azjezz azjezz pinned this issue Nov 8, 2021
@azjezz azjezz added Priority: High After critical issues are fixed, these should be dealt with before any further issues. Status: In Progress This issue is being worked on, and has someone assigned. Type: Documentation Updating documentation labels Nov 8, 2021
@azjezz
Copy link
Owner Author

azjezz commented Nov 8, 2021

@azjezz
Copy link
Owner Author

azjezz commented Dec 3, 2021

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

@azjezz
Copy link
Owner Author

azjezz commented Dec 3, 2021

@azjezz
Copy link
Owner Author

azjezz commented Dec 3, 2021

shell component is now documented:

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

@veewee
Copy link
Collaborator

veewee commented Dec 4, 2021

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

@azjezz
Copy link
Owner Author

azjezz commented Dec 4, 2021

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
Copy link
Owner Author

azjezz commented Dec 4, 2021

runtime component is now documented:

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

@azjezz
Copy link
Owner Author

azjezz commented Dec 4, 2021

shell exceptions are now documented:

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

@azjezz
Copy link
Owner Author

azjezz commented Dec 4, 2021

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

@azjezz
Copy link
Owner Author

azjezz commented Dec 4, 2021

json component is now documented:

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

@azjezz
Copy link
Owner Author

azjezz commented Dec 5, 2021

iter component is now documented:

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

@veewee
Copy link
Collaborator

veewee commented Dec 5, 2021

@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
Copy link
Owner Author

azjezz commented Dec 6, 2021

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:
image

Html after:
image

Shell before:
image

Shell after:
image

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:

image

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

image

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
Copy link
Collaborator

veewee commented Dec 6, 2021

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

@azjezz
Copy link
Owner Author

azjezz commented Dec 6, 2021

couple of solutions:

image

image

image

@azjezz
Copy link
Owner Author

azjezz commented Dec 6, 2021

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:
image

after:

image

@azjezz
Copy link
Owner Author

azjezz commented Dec 6, 2021

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.

image

@veewee
Copy link
Collaborator

veewee commented Dec 6, 2021

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

@azjezz
Copy link
Owner Author

azjezz commented Dec 6, 2021

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

@azjezz
Copy link
Owner Author

azjezz commented Dec 6, 2021

done 🎉
image

@azjezz
Copy link
Owner Author

azjezz commented Dec 8, 2021

async component is now documented:

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

@VincentLanglet
Copy link

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
Copy link
Owner Author

azjezz commented Dec 17, 2021

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
Copy link
Owner Author

azjezz commented Dec 18, 2021

fun, and promise components are now documented:

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

@azjezz
Copy link
Owner Author

azjezz commented Dec 18, 2021

TCP component is now documented:

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

@azjezz
Copy link
Owner Author

azjezz commented Dec 18, 2021

Unix component is now documented:

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

@veewee
Copy link
Collaborator

veewee commented Dec 18, 2021

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
Copy link
Owner Author

azjezz commented Dec 19, 2021

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 )

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Priority: High After critical issues are fixed, these should be dealt with before any further issues. Status: In Progress This issue is being worked on, and has someone assigned. Type: Documentation Updating documentation Type: Enhancement Most issues will probably ask for additions or changes.
Projects
None yet
Development

No branches or pull requests

3 participants