PHPDoc Cleanup

[erayd]

The current codebase lacks useful PHPDoc comments in many places, and needs a significant overhaul.

I would like to propose the following:

• Every class and interface must have:
  • A short description of what the class
  • A long description explaining the class in more depth if appropriate
  • @package justinrainbow/json-schema
  • @license MIT
• Every method must have:
  • A short description of the method
  • A long description explaining the method in more depth if appropriate
  • @api if the method is part of the official public API
  • @param <type> <name> for all parameters; mixed-type params should be stated as mixed
  • @return <type> [description] for all methods which return a value. The return description should be present for any method where the return value is not self-evident from reading the method description.
• Every abstract method signature should be documented as per fully-defined methods.
• Every property must have:
  • @var <type> <description>
• Every class constant must have a PHPDoc description, but should not contain any @tags.

I would also like to add a config file for sami/sami, and delete the old documentation directory - docs hasn't been touched in 5+ years, and doesn't contain anything of substance anyway. Sami should not be added as a dev-time dependency, as it requires PHP >= 7.0 to run.

Before I go ahead and sink time into this, does what I've outlined above sound reasonable?

Finally, if someone else is keen and has the time, feel free to jump in with a PR. I'm quite happy to do all the work on this, but documentation isn't my favourite activity, so if you happen to harbour a secret passion for it...

[bighappyface]

Sounds good to me

[shmax]

Sure, sounds good. I recently went through the whole process of using Sami to deploy its output to github pages for a different project, so I can help with travis if you'd like to do something similar.

[erayd]

@shmax That would definitely be nice if you're willing to do that again here :-).

[shmax]

Can do, but we'll need someone with access to the settings to configure github pages. @bighappyface?

[erayd]

Oh. If that needs admin access, then we're SOL on that front, because @bighappyface isn't, and @justinrainbow is gone.

[shmax]

Ugh. Well, we could always deploy it somewhere else. Any ideas?

[erayd]

I have a webserver on DigitalOcean we can put this on, if that's a viable option. It has various PHP websites on it, but nothing too heavy-duty, and there's a fair bit of spare capacity on there.

[shmax]

That could work. We don't even need PHP; just anything that can host static pages. I've only deployed to github, but I've been meaning to learn how to do other destinations, so this will be interesting. Should this work happen independently of your PHPDoc stuff, or in concert?

[erayd]

Independently I reckon. Stand by, and I'll add a user account to the server for you.

[shmax]

Take your time, I'm off to bed. Should be able to dabble with this a bit on Sunday.

[erayd]

Already done it :-). See Slack.

[bighappyface]

^^ nvm

[erayd]

What do you guys think should be done with the @author tags? Are they still relevant, noting how many people have contributed to this library over the years?

If we keep them, how do we determine who is tagged - do we just tag everyone who has current code in the file where the tag appears, and not care about the list being huge?

Personally, I think it makes more sense to have a CONTRIBUTORS or AUTHORS file in the repo root that lists contributors, and remove the @author tags completely, as they get unweildy when there are a large number of contributors.