Fix grammar ("an URL" should be "a URL") and consistent use of URL (not "url" / "Url") in documentation only, part 1

Amazing how much work goes into a 'simple' documentation-only consistent terminology fix!

The latest patch addresses everything in #125, in particular not incorrectly capitalizing literal string keys.

I applied the patch locally and reviewed it with git diff --staged --color-words to ensure all the changes were correct and stayed within scope. The only issue I found was:

+++ b/core/tests/Drupal/Tests/Component/Utility/UrlHelperTest.php
@@ -612,12 +612,12 @@ public function providerTestExternalIsLocal() {
-   * Tests invalid url arguments.
+   * TTests invalid URL arguments.

Oops, typo here -- a double T.

I then grepped the codebase for instances of " url" and " Url" in documentation lines. I've manually removed things where url is part of a permission string or array key only (versus a word in a sentence.) There are still a LOT left with the patch applied.

From:

[ayrton:drupal | Thu 15:33:42] $ grep -r " url" * | grep "\* " | grep -v "vendor" | grep -v "node_modules"

These still have lowercase uses that need to be changed:

core/tests/Drupal/Tests/Core/DrupalTest.php:   * Tests the urlGenerator() method.
core/tests/Drupal/Tests/Component/Utility/UrlHelperTest.php:   * Enhances test urls with schemes.
core/tests/Drupal/Tests/Component/Utility/UrlHelperTest.php:   *   The list of urls.
core/tests/Drupal/Tests/Component/Utility/UrlHelperTest.php:   * Enhances test urls with prefixes.
core/tests/Drupal/Tests/Component/Utility/UrlHelperTest.php:   *   The list of urls.
core/tests/Drupal/Tests/Component/Utility/UrlHelperTest.php:   * Tests detecting external urls that point to local resources.
core/includes/theme.inc: *     route_name + route_parameters or url (path), language, and query options
core/lib/Drupal/Core/Entity/Controller/EntityController.php:   * The url generator.
core/lib/Drupal/Core/Mail/MailFormatHelper.php:   * Internal array of urls replaced with tokens.
core/lib/Drupal/Core/Routing/RouteProvider.php:   * restrictions on the url. That case is considered a not found - returning
core/lib/Drupal/Core/Routing/RouteProvider.php:   *   RouteCollection with all urls that could potentially match $request.
core/lib/Drupal/Core/Routing/UrlGenerator.php:   * The path processor to convert the system path to one suitable for urls.
core/lib/Drupal/Core/Routing/UrlGenerator.php:   *   The path processor to convert the system path to one suitable for urls.
core/lib/Drupal/Core/Routing/RouteProviderInterface.php:   * restrictions on the url. That case is considered a not found - returning
core/lib/Drupal/Core/EventSubscriber/MaintenanceModeSubscriber.php:   *   The url generator.
core/lib/Drupal/Core/Utility/LinkGenerator.php:   *   The url generator.
core/lib/Drupal/Core/Utility/LinkGenerator.php:   *   The link text, url, and other options.
core/modules/jsonapi/tests/src/Functional/NodeTest.php:   * Tests PATCHing a node's path with and without 'create url aliases'.
core/modules/file/tests/src/Kernel/FileUrlTest.php: * Tests the file url.
core/themes/olivero/templates/navigation/menu.html.twig: *   - url: The menu link url, instance of \Drupal\Core\Url
core/themes/olivero/templates/navigation/menu--primary-menu.html.twig: *   - url: The menu link url, instance of \Drupal\Core\Url
core/themes/olivero/templates/navigation/menu--secondary-menu.html.twig: *   - url: The menu link url, instance of \Drupal\Core\Url

From:

[ayrton:drupal | Thu 15:40:35] $ grep -r " url" * | grep " // " | grep -v "vendor" | grep -v "node_modules"

core/tests/Drupal/FunctionalTests/Update/UpdatePathTestBase.php:    // Set the update url. This must be set here rather than in
core/tests/Drupal/Tests/BrowserTestBase.php:    // Generate a route to prime the url generator with the correct base url.
core/tests/Drupal/Tests/Component/Utility/UrlHelperTest.php:      // Invalid destination urls.
core/lib/Drupal/Core/Form/ConfirmFormHelper.php:        // Suppress the exception and fall back to the form's cancel url.
core/lib/Drupal/Core/Asset/JsOptimizer.php:    // Remove JS source and source mapping urls or these may cause 404 errors.
core/lib/Drupal/Core/Field/Plugin/Field/FieldFormatter/EntityReferenceEntityFormatter.php:      // entity's url. Since we don't know what the markup of the entity will
core/lib/Drupal/Core/Command/DbCommandBase.php:    // Load connection from a url.
core/lib/Drupal/Core/Installer/Form/SelectLanguageForm.php:      // removed from the url.
core/modules/jsonapi/tests/src/Kernel/Normalizer/JsonApiDocumentTopLevelNormalizerTest.php:        // Ensure that resource link contains url with the alias field.
core/modules/file/tests/src/Functional/DownloadTest.php:    // Try requesting the private file url without a file specified.
core/modules/views_ui/tests/src/Functional/DisplayPathTest.php:    // Links should be url-encoded.
core/modules/views_ui/src/ViewEditForm.php:      // Find out the first display which has a changed path and redirect to this url.
core/modules/toolbar/tests/src/Nightwatch/Tests/toolbarApiTest.js:        // Clear escapeAdmin url values.
core/modules/toolbar/tests/src/Nightwatch/Tests/toolbarTest.js:        // Clear escapeAdmin url values.
core/modules/language/tests/src/Functional/LanguageBrowserDetectionAcceptLanguageTest.php:    // Set language detection to url and browser detection.
core/modules/language/tests/src/Kernel/EntityUrlLanguageTest.php:    // from overwriting the url.
core/modules/user/tests/src/Functional/UserPasswordResetTest.php:    // Ensure that the current url does not contain the hash and timestamp.
core/modules/user/src/Plugin/views/argument_validator/UserName.php:    // argument so it works for example for generation summary urls.
core/modules/forum/src/Controller/ForumController.php:          // the url.
core/modules/system/tests/src/Functional/System/AdminTest.php:    // match the redirected url.
core/modules/system/tests/src/Kernel/Mail/MailTest.php:    // Test root relative urls.
core/modules/system/tests/src/Kernel/Mail/MailTest.php:    // Test protocol relative urls.
core/modules/system/tests/src/Kernel/Mail/MailTest.php:    // Test absolute urls.
core/modules/taxonomy/tests/src/Functional/TermAutocompleteTest.php:    // Retrieve the autocomplete url.
core/modules/taxonomy/tests/src/Functional/Views/TaxonomyIndexTidUiTest.php:    // Visit the view's page url and validate the results.
core/modules/ckeditor5/ckeditor5.module:        // CSS url is external or relative to Drupal root.
core/modules/ckeditor5/ckeditor5.module:        // CSS url is relative to theme.
core/modules/filter/filter.module:  // and allow @ in a url, but only in the middle. Catch things like http://example.com/@user/
core/modules/node/tests/src/Functional/NodeTranslationUITest.php:    // Need to check from the beginning, including the base_path, in the url
core/modules/views/js/ajax_view.js:        // If there is a '?' in ajaxPath, clean url are on and & should be
core/modules/views/js/base.js:    // Get viewPath url without baseUrl portion.
core/modules/views/js/base.js:    // 3 is the length of the '?q=' added to the url without clean urls.
core/modules/views/tests/src/Functional/Plugin/DisplayTest.php:    // Test more link with absolute url.
core/modules/views/tests/src/Functional/Plugin/DisplayTest.php:    // Test more link with query parameters in the url.
core/modules/views/tests/src/Functional/Plugin/DisplayTest.php:    // Test more link with fragment in the url.
core/modules/views/src/Plugin/views/display/DisplayPluginBase.php:    // Return the display URL if there is no custom url.
core/modules/views/src/Plugin/views/display/DisplayPluginBase.php:    // Create url.

From:
[ayrton:drupal | Thu 15:36:55] $ grep -r " Url" * | grep " \* " | grep -v "vendor" | grep -v "node_modules"

The following are outstanding. Many refer to "Url object" and might mean that in the sense that they are Drupal\Core\Url objects, but describing them in a sentence "URL object" is more correct if we're not using the full namespace. Or, basically, I disagree with #107 and agree with #114. :)

core/tests/Drupal/Tests/Core/Form/FormSubmitterTest.php:   * Tests redirectForm() when a redirect is a Url object.
core/tests/Drupal/Tests/Core/Template/TwigSandboxTest.php:   * Tests that safe methods inside Url objects can be called.
core/tests/Drupal/Tests/Core/UrlTest.php:   *   An array of Url objects.
core/tests/Drupal/Tests/Core/UrlTest.php:   *   An array of Url objects.
core/tests/Drupal/Tests/Core/UrlTest.php:   *   An array of Url objects.
core/tests/Drupal/Tests/Core/UrlTest.php:   *   An array of Url objects.
core/tests/Drupal/Tests/ApiRequestTrait.php:   * convert Drupal Url objects to strings.
core/includes/form.inc: *   (optional) Either a path or Url object to redirect to when the batch has
core/lib/Drupal/Core/Link.php:   * Creates a Link object from a given Url object.
core/lib/Drupal/Core/Link.php:   *   The Url to create the link for.core/lib/Drupal/Core/File/FileUrlGeneratorInterface.php: * as plain strings or Url objects, depending on the requirements. In general,
core/lib/Drupal/Core/File/FileUrlGeneratorInterface.php:   *   For a local URL (matching domain), a base-relative Url object containing
core/lib/Drupal/Core/File/FileUrlGeneratorInterface.php:   *   a URL that may be used to access the file. An Url object with absolute
core/lib/Drupal/Core/File/FileUrlGeneratorInterface.php:   *   setAbsolute() on the Url object to build an absolute URL.
core/lib/Drupal/Core/Url.php:   * Constructs a new Url object.
core/lib/Drupal/Core/Url.php:   * constructing Url objects directly in order to avoid ambiguity and make your
core/lib/Drupal/Core/Url.php:   * Creates a new Url object for a URL that has a Drupal route.
core/lib/Drupal/Core/Url.php:   *   A new Url object for a routed (internal to Drupal) URL.
core/lib/Drupal/Core/Url.php:   * Creates a Url object for a relative URI reference submitted by user input.
core/lib/Drupal/Core/Url.php:   *   A new Url object based on user input.
core/lib/Drupal/Core/Url.php:   * Creates a new Url object from a URI.
core/lib/Drupal/Core/Url.php:   *   A new Url object with properties depending on the URI scheme. Call the
core/lib/Drupal/Core/Url.php:   * Create a new Url object for entity URIs.
core/lib/Drupal/Core/Url.php:   *   A new Url object for an entity's canonical route.
core/lib/Drupal/Core/Url.php:   * Creates a new Url object for 'internal:' URIs.
core/lib/Drupal/Core/Url.php:   *   A new Url object for an 'internal:' URI.
core/lib/Drupal/Core/Url.php:   * Creates a new Url object for 'route:' URIs.
core/lib/Drupal/Core/Url.php:   *   A new Url object for a 'route:' URI.
core/lib/Drupal/Core/Url.php:   * Returns the Url object matching a request.
core/lib/Drupal/Core/Url.php:   * by the current user to allow storing and reusing Url objects by different
core/lib/Drupal/Core/Url.php:   * router name and parameters stored in the Url object returned by this
core/lib/Drupal/Core/Url.php:   *   A Url object. Warning: the object is created even if the current user
core/lib/Drupal/Core/Url.php:   * Generates a URI string that represents the data in the Url object.
core/lib/Drupal/Core/Url.php:   *   A URI representation of the Url object data.
core/lib/Drupal/Core/Url.php:   * Returns the URI value for this Url object.
core/lib/Drupal/Core/Url.php:   * Sets the value of the absolute option for this Url.
core/lib/Drupal/Core/Url.php:   * Generates the string URL representation for this Url object.
core/lib/Drupal/Core/Url.php:   * If this Url object was constructed from a Drupal route or from an internal
core/lib/Drupal/Core/Url.php:   * Checks this Url object against applicable access check services.
core/lib/Drupal/Core/Menu/MenuLinkInterface.php:   *   A Url object, or NULL if there is no route (e.g. when the link is not
core/lib/Drupal/Core/Menu/MenuLinkInterface.php:   *   A Url object, or NULL if there is no route because there is no custom
core/lib/Drupal/Core/Menu/MenuLinkInterface.php:   *   A Url object, or NULL if there is no route (e.g. when the link is not
core/lib/Drupal/Core/Menu/menu.api.php: *   - url: a Url object.
ore/modules/jsonapi/src/JsonApiResource/Link.php:   *   The Url object for the link.
core/modules/jsonapi/src/JsonApiResource/Link.php:   *   The link's URI as a Url object.
core/modules/jsonapi/src/JsonApiResource/ResourceObject.php:   * Gets a Url for the ResourceObject.
core/modules/menu_link_content/src/MenuLinkContentInterface.php:   *   A Url object instance.
core/modules/link/src/LinkItemInterface.php:   *   Returns a Url object.
core/modules/link/src/Plugin/Field/FieldFormatter/LinkFormatter.php:   *   A Url object.
core/modules/field_ui/src/Form/EntityDisplayFormBase.php:   * Returns the Url object for a specific entity (form) display edit form.
core/modules/field_ui/src/Form/EntityDisplayFormBase.php:   *   A Url object for the overview route.
core/modules/views/src/Plugin/views/display/DisplayPluginBase.php:   *   The more link as Url object.
core/modules/views/src/ViewExecutable.php:   * Gets the Url object associated with the display handler.
core/modules/rest/tests/src/Functional/ResourceTestBase.php:   * convert Drupal Url objects to strings.
core/themes/claro/claro.theme: * $link['#options']['attributes'] and from the Url object's.

From:
[ayrton:drupal | Thu 15:47:04] $ grep -r " Url" * | grep " // " | grep -v "vendor" | grep -v "node_modules"

core/lib/Drupal/Core/Render/Element/PathElement.php:        // We do the value conversion here whilst the Url object is in scope
core/modules/link/tests/src/Unit/Plugin/Validation/Constraint/LinkAccessConstraintValidatorTest.php:      // Mock a Url object that returns a boolean indicating user access.
core/modules/views/src/Plugin/views/field/FieldPluginBase.php:    // Build the link based on our altered Url object, adding on the optional
core/modules/views/src/Plugin/views/row/RssFields.php:    // it through a Url object to allow outbound path processors to run (path
core/themes/claro/claro.theme:  // the attributes of the Url object are processed during rendering.

That is so many things that I would actually like to commit this issue, with the "TTests" thing fixed, and then have a followup for all those other ones. So, I fixed that on commit:

diff --git a/core/tests/Drupal/Tests/Component/Utility/UrlHelperTest.php b/core/tests/Drupal/Tests/Component/Utility/UrlHelperTest.php
index 61262997dc..2b540e3980 100644
--- a/core/tests/Drupal/Tests/Component/Utility/UrlHelperTest.php
+++ b/core/tests/Drupal/Tests/Component/Utility/UrlHelperTest.php
@@ -636,7 +636,7 @@ public function providerTestExternalIsLocal() {
   }
 
   /**
-   * TTests invalid URL arguments.
+   * Tests invalid URL arguments.
    *
    * @param string $url
    *   The URL to test.

So, there are two followup issues to handle, IMO. One where url is used in a sentence and obviously wrong, and one where we can disagree about whether a Url object is correct or not.

Meanwhile, pushed to 10.1.x, and cherry-picked to 10.0.x and 9.5.x. Thanks everyone for your persistence on this issue! Let's create those two followup issues.

Posted 📌 Correctly capitalize "url" in documentation only, part 2 Fixed for the first followup.

Automatically closed - issue fixed for 2 weeks with no activity.

Created the last followup, 📌 Correctly capitalize "Url object" in documentation only, part 3 Closed: duplicate

quietone → credited anavarre → .

quietone → credited capysara → .

quietone → credited jungle → .

quietone → credited Kevin P Davison → .

quietone → credited klausi → .

quietone → credited Lal_ → .

quietone → credited mahaveer003 → .

quietone → credited mohrerao → .

quietone → credited pk188 → .

quietone → credited Ramya Balasubramanian → .

quietone → credited ravi.shankar → .

quietone → credited yogeshmpawar → .

I closed 📌 In the documentation, change all instances of "url" to "URL". Closed: duplicate as a duplicate and am adding credit.