uri: Unify example URL for RFC 3986 getters - #5471
Conversation
|
My original idea was to use a basic example just to illustrate the basic behavior of each method, and then to add another example to illustrate the specification specific behavior (wrt. normalization or IDNA). I'm not sure that people less familiar with URI topic will have an easy time to understand what's going on if they are presented such a long and complex URI. IMO the example would be more clear if the URI was shorter. An example: It's (more) difficult to find the fragment in the latter example, even for me, since there are a lot of unrelated symbols to skip. |
I think those folks in particular can benefit when all the examples use the same URL, since they can then compare the different getters to see which of the getters relates to which part of the URL. Having different URLs where some of the parts are left out can result in ambiguity. For example using Basically when I look at the documentation page for a specific getter, then I'm interested in the specifics of that getter. I think simpler URLs are better suited for the documentation of the constructor or |
This new example URL includes all possible components and each of the component includes a meaningful difference between the “normalized” and “raw” version to make it easy for a reader to see what each of the getters refers to and what kind of normalization to expect.
Co-authored-by: Louis-Arnaud <la.catoire@gmail.com>
1571067 to
2ccde7e
Compare
The example rewrites in the RFC 3986 getter pages overlap with php#5471, which unifies the example URL across all of them; reverting them here leaves the two pull requests disjoint. The normalization entities and the wording changes stay. Also corrects four points in what is left: - the normalization entity omitted dot segment removal, which is what getPath() visibly does - the non-normalization entity claimed components are returned in their original form, which toRawString() and a resolved getRawPath() both contradict - getPort() does normalize, it drops leading zeros, so the page keeps its wording - Ipv4InIpv6InvalidCodePoint is also raised for an empty part, a leading zero and too many parts, not only for an invalid code point
This new example URL includes all possible components and each of the component includes a meaningful difference between the “normalized” and “raw” version to make it easy for a reader to see what each of the getters refers to and what kind of normalization to expect.