class docs for Url should give an overview of how to create one

Added to the comment there to point developers towards those static methods, and added a See Also entry for EntityBase::toUrl.

Pls consider this one.

So I thought that I'd fixed this documentation gap, like... five years ago. Turns out, the improvements never got committed because they were tied up in an API addition: #2417459: Provide internal API for special schemes and thin public wrappers for user input and non-routed URLs

Here's the docblock that was being added there:

+++ b/core/lib/Drupal/Core/Url.php
@@ -18,11 +18,98 @@
+ *
+ * This class supports:
+ * - External URLs.
+ * - Internal URLs that correspond to routes handled by Drupal's routing system.
+ * - Base-relative and host-relative URLs not handled by Drupal.
+ * - URLs for user input.
+ * - URLs for entities.
+ *
+ * New URLs should generally be constructed using one of the static factory
+ * methods. See:
+ * - Url::fromRoute()
+ * - Url::fromRouteMatch()
+ * - Url::fromUri()
+ * - Url::fromUserInput()
+ * - Url::fromBaseRelativePath()
+ * - Url::fromHostRelativePath()

Can we verify that's all correct information still, and include whatever of it is accurate in the patch here? Edit: the fromBaseRelativePath() and fromHostRelativePath() methods don't exist in HEAD, but the rest presumably still do.

As a followup, we should perhaps create a "URL generation" API topic, or perhaps add to the routing topic and make it "Routing and URL generation".

As a docs improvement, this is eligible for backport to the production branch. Thanks!

Err, so I apparently forgot that I'd committed this locally before pushing a different commit. Rather than reverting it, though, let's iterate on it based on #11. Usually I would either revert or ask for a new issue, but the current version is adding information that's better than the nothing that was there in HEAD... so let's continue to work on this in this issue on top of the previous commit. Thanks!

Might as well make the branches consistent for less confusion while I'm at it.

I have applied the patch. Kindly review the patch

Set to NR to trigger the test.

I created two followups, one for the question in #11 #3269790: Improve class doc of core/lib/Drupal/Core/Url.php and the other is the followup requested in #11, #3269789: Add URL generation API topic. I made one for the question so that it can be handled on it's own, without code changes. It just keeps things simple.

That is everything to do here.

From my reading of the issue history, the original fix was already committed and pushed. The necessary follow-ups now exist (thanks @quietone!). So I believe this is safe to call "fixed".