Document special route names

Added documentation for three special routing names.

1. +++ b/core/lib/Drupal/Core/Routing/NullGenerator.php
   @@ -29,6 +29,14 @@ public function __construct(RequestStack $request_stack) {
   +   * - <none>: The special path that make links relative to the current URL.
   

   "Special path" makes no sense, it should be only "Path"

2. +++ b/core/lib/Drupal/Core/Routing/NullGenerator.php
   @@ -29,6 +29,14 @@ public function __construct(RequestStack $request_stack) {
   +   * ¶
   

   Remove white space.

Fixed coding standards issues and suggestions.

Mh, the null generator doesn't really seem to be the best place to document it, don't you think so? This class is for example not used on runtime. Maybe the drupal specific url generator: \Drupal\Core\Routing\UrlGeneratorInterface is a better place.

Yes to #6. Also:

+++ b/core/lib/Drupal/Core/Routing/NullGenerator.php
@@ -29,6 +29,14 @@ public function __construct(RequestStack $request_stack) {
+   *
+   * Available names:
+   * - <front>: The special path that links to the default front page.
+   * - <current>: The special path that links to the current page.
+   * - <none>: Path that make links relative to the current URL.
+   *
+   * @param string $name
+   *   String of routing paths.

This whole documentation area doesn't make sense to me ...

What does "available" names mean?

Also shouldn't it be part of the $name parameter docs?

Also the grammar needs attention.

<current> would be to get current page url.
<none> is a menu link with a path to nowhere. See this https://www.drupal.org/node/143322 page which has two issues for Drupal 8:

1. Allow menu items without path
2. Add to allow for non-link links

First one is marked duplicate of Second and Second is fixed, so should we use <nolink> here?

Correct me if I am totally in the wrong direction.

This one should do.

Sorry , ignore that one.

I am working on it

I have added review comments for the patch posted on #2719611: Document special route names.

1. +++ b/core/lib/Drupal/Core/Routing/NullGenerator.php
   @@ -29,6 +29,15 @@ public function __construct(RequestStack $request_stack) {
       * generate(), generateFromRoute(), and getPathFromRoute() all call this
   

   Please update doc comment with capital letter, like 'Functions generate(), generateFromRoute(), and getPathFromRoute() all call this protected method.'

2. +++ b/core/lib/Drupal/Core/Routing/NullGenerator.php
   @@ -29,6 +29,15 @@ public function __construct(RequestStack $request_stack) {
   +   *   String of routing paths.
   

   Please replace this with 'The special string that generates a routing path.' If you think replacement makes more sense.

3. +++ b/core/lib/Drupal/Core/Routing/NullGenerator.php
   @@ -29,6 +29,15 @@ public function __construct(RequestStack $request_stack) {
   +   *
   

   Remove this line, as the following line also continuity of the description of $name parameter.

4. +++ b/core/lib/Drupal/Core/Routing/NullGenerator.php
   @@ -29,6 +29,15 @@ public function __construct(RequestStack $request_stack) {
   +   * This defines the following special routes:
   

   Indentation, (Parameter comment indentation must be 3 spaces)

5. +++ b/core/lib/Drupal/Core/Routing/NullGenerator.php
   @@ -29,6 +29,15 @@ public function __construct(RequestStack $request_stack) {
   +   * This defines the following special routes:
   +   * - <front>: The site's front page.
   +   * - <current>: The current page.
   +   * - <none>: The path that make links relative to the current URL.
   

   Indentation, (Parameter comment indentation must be 3 spaces)

6. +++ b/core/lib/Drupal/Core/Routing/NullGenerator.php
   @@ -29,6 +29,15 @@ public function __construct(RequestStack $request_stack) {
   +   *
   

   Remove this additional blank line.

Made changes suggested in comment #19

I think one thing we should do is to focus our documentation on the bits which are actually used most of the time in the production level environment:

\Drupal\Core\Routing\UrlGeneratorInterface::generateFromRoute and \Drupal\Core\Url. Both \Drupal\Core\Url::fromRoute and \Drupal\Core\Routing\UrlGeneratorInterface::generateFromRoute don't document these special routes. I personally believe putting this information there would be way better.

I think one thing we should do is to focus our documentation on the bits which are actually used most of the time in the production level environment:

\Drupal\Core\Routing\UrlGeneratorInterface::generateFromRoute and \Drupal\Core\Url. Both \Drupal\Core\Url::fromRoute and \Drupal\Core\Routing\UrlGeneratorInterface::generateFromRoute don't document these special routes. I personally believe putting this information there would be way better.

+++ b/core/lib/Drupal/Core/Routing/NullGenerator.php
@@ -27,8 +27,15 @@ public function __construct(RequestStack $request_stack) {
+   * Functions generate(), generateFromRoute(), and getPathFromRoute() all call this

Line exceeding 80 characters

Modified one line which contain more than 80 characters. Applying the patch.

Neither of the latest comment got addressed in your latest patch. Please reach out if you need help.

Made changes as per the suggestion in comment #25 , Please Review the patch and correct me if i am wrong.

My feeling is that documentation should be close to the code that it's documenting, so that if the special routes ever change, or are added to or removed, we notice the documentation change that would also be required.

But we could put a @see in both \Drupal\Core\Url::fromRoute and \Drupal\Core\Routing\UrlGeneratorInterface::generateFromRoute that points here.

That's a tricky question ... for me having duplicate documentation is better than having people troubling with finding it in the first place.

Re-rolled for 9.2

Patch #40 applied successfully. Adding screenshots of diff for reference. RTBC +1

@mitthukumawat, thanks for the interest. Reviewing a patch will help an issue move forward. The contributor guide contains move information about contributing.

Applied patch #40 in drupal-9.3.x-dev applied successfully
After patch getting expected result mention in tickets
Thanks for the patch

The patch looks good for me to change to RTBC, but I'm just worried about #31 and #32, should we keep the duplicated documentation?

As the $options param from the Url construct function:

   * @param array $options
   *   See \Drupal\Core\Url::fromUri() for details.
   *

Shouldn't we do the same thing for the route_name?
Something like

   * @param string $route_name
   *   @see \Drupal\Core\Routing\NullGenerator.php::getRoute for details.
   *

The Needs Review Queue Bot tested this issue. It either no longer applies to Drupal core, or fails the Drupal core commit checks. Therefore, this issue status is now "Needs work".

Apart from a re-roll or rebase, this issue may need more work to address feedback in the issue or MR comments. To progress an issue, incorporate this feedback as part of the process of updating the issue. This helps other contributors to know what is outstanding.

Consult the Drupal Contributor Guide to find step-by-step guides for working with issues.

The Needs Review Queue Bot tested this issue. It fails the Drupal core commit checks. Therefore, this issue status is now "Needs work".

Apart from a re-roll or rebase, this issue may need more work to address feedback in the issue or MR comments. To progress an issue, incorporate this feedback as part of the process of updating the issue. This helps other contributors to know what is outstanding.

Consult the Drupal Contributor Guide to find step-by-step guides for working with issues.

I had Reviewed the patch and it's working as expected mentioned in comment #52

great work joachim, patch is all working fine and thanks ranjit for reviewing, reviewing a patch will help an issue move forward. The contributor guide contains move information about contributing.

<?php

namespace Drupal\Core;

/**
 * This class holds a <span> generated from the <nolink> route.
 */
class GeneratedNoLink extends GeneratedLink {

  /**
   * {@inheritdoc}
   */
  const TAG = 'span';

}

<nolink> is a special route too, which is not documented by the patch here, is it irrelevant here?

Not a bug, could be a Minor

Apply the issue summary(IS) template only. If #55 is a thing, then needs updating IS.

@jungle that is a valid route that can be added to the link so think it should be included as well.

Addressed #58 and added to the patch

Fixed CCF from #59

Patch #60 is applied successfully and screenshot is also attached.

Checked the patch given in #60 works properly

1. +++ b/core/lib/Drupal/Core/Routing/NullGenerator.php
   @@ -28,6 +28,14 @@ public function __construct(RequestStack $request_stack) {
   +   *   - <nolink>: Used to enter a link, but only the text of the link to be shown, without actually creating a link.
   

   This needs wrapping at 80 characters.

2. +++ b/core/lib/Drupal/Core/Routing/UrlGeneratorInterface.php
   @@ -15,7 +15,13 @@ interface UrlGeneratorInterface extends SymfonyUrlGeneratorInterface {
   +   *   @see \Drupal\Core\Routing\NullGenerator.php::getRoute
   

   This @see is not valid; it can't be part of @param and the .php extension shouldn't be added to the class name. Not even sure we need an @see here?

Attaching patch and interdiff for the issue mentioned in comment #63

Build failure in #64

removing errors from patch #64

Please try this patch for 10.1.x

+   *   - <nolink>: Used to enter a link,
+   *   but only the text of the link to be shown,
+   *   without actually creating a link.

that visually just doesn't read right.

Modified the patch as requested.

Adding again with modification of #69.

same patch for 11.x.

Patch #70 has successfully passed the test in version 11.x, hence it should be moved to the "needs review"

The Needs Review Queue Bot tested this issue.

While you are making the above changes, we recommend that you convert this patch to a merge request. Merge requests are preferred over patches. Be sure to hide the old patch files as well. (Converting an issue to a merge request without other contributions to the issue will not receive credit.)

So #72 was not needed as #70 still applies cleanly to 11.x, same for the MR Ticket could of been put back into RTBC

+++ b/core/lib/Drupal/Core/Routing/NullGenerator.php
@@ -28,6 +28,16 @@ public function __construct(RequestStack $request_stack) {
+   *   - <nolink>: Used to create text that appears as a link,
+   *   but does not lead to an actual URL, only the text
+   *   of the link is displayed without an actual link.

The second/third lines of the bullet point need to be indented another two characters. Also this can be wrapped more closely to 80 characters.

Same for the other instances of this.

Updated as per #81

#81 indentation has been addressed.

Still not sure this is quite right, added some more suggestions.