Document ext/uri

[kocsismate]

Another attempt to document ext/uri after #5060

Some of my sentences are very clunky, so I am happy to receive suggestions.

[TimWolla]

First pass at comments. Didn't yet look at all files, but this looks like a good start. Will take another look after you reviewed my comments to avoid looking at all files twice in case they change.

[TimWolla]

Here it might make sense to also link to Uri\WhatWg\Url::withUsername (second position).

Suggested change

	<member><methodname>Uri\WhatWg\Url::getPassword</methodname></member>
	<member><methodname>Uri\WhatWg\Url::getPassword</methodname></member>
	<member><methodname>Uri\WhatWg\Url::withUsername</methodname></member>

[kocsismate]

I think doing so would make more sense for Uri because password is just a pseudo component together with username. For WHATWG URL, they are completely separate components with not much more connection than e.g. the host and port. I'm not against adding it though, so if you have a strong opinion, then I'm fine with it.

[TimWolla]

Suggested change

	<member><methodname>Uri\Rfc3986\Uri::toRawString</methodname></member>
	<member><methodname>Uri\Rfc3986\Uri::toString</methodname></member>
	<member><methodname>Uri\Rfc3986\Uri::toString</methodname></member>

I think having just one here is sufficient to point users into the right direction.

[kocsismate]

I wouldn't pick just one of the toString methods, and in the same way, I wouldn't pick only one of the getters. I think including both variants wouldn't hurt, and if someone actually wants to look up the omitted variant then the extra link saves them an extra navigation step.

All in all, IMO it's not a huge deal either way, but I pretty much like the completeness here.

[TimWolla]

Suggested change

	<member><methodname>Uri\Rfc3986\Uri::toRawString</methodname></member>
	<member><methodname>Uri\Rfc3986\Uri::toString</methodname></member>
	<member><methodname>Uri\Rfc3986\Uri::toString</methodname></member>

Also applies to the other getters (if they list both the raw and normalized versions).

[TimWolla]

Suggested change

	<?php
	$url = \Uri\WhatWg\Url::parse("https://example.com");
	if ($url === null) {
	echo "Invalid URL"
	} else {
	echo "Valid URL " . $uri->toAsciiString();
	}
	?>
	<?php
	$url = \Uri\WhatWg\Url::parse("https://example.com");
	if ($url !== null) {
	echo "Valid URL ", $url->toAsciiString();
	} else {
	echo "Invalid URL";
	}
	?>

[kocsismate]

Sorry, I don't like the echo "...", "" construct, so I left this one out from the changes. I think regular concatenation is more widely known

[TimWolla]

Is it actually called uri in the stubs? 🙈

[kocsismate]

Yes, because uri tries to suggest that relative references are also possible (which are called by WHATWG URL as "relative URL strings"). This was my best idea back then.