Make the documentation comment for the module clearer

Created on 8 August 2024, 6 months ago
Updated 10 August 2024, 6 months ago

In the documentation comment for the Menu Example module, the following sentence needs to be corrected.

In drupal, a route is a path which is returns some response.

drupal is not capitalized; which is returns is not grammatically correct.

The correct sentence is the following one.

In Drupal, a route is a path which returns some response.

📌 Task
Status

Postponed

Version

4.0

Component

Menu Example

Created by

Live updates comments and jobs are added and updated live.
  • Needs issue summary update

    Issue summaries save everyone time if they are kept up-to-date. See Update issue summary task instructions.

Sign in to follow issues

Comments & Activities

  • 🇮🇹Italy apaderno Brescia, 🇮🇹
  • 🇮🇹Italy apaderno Brescia, 🇮🇹
  • 🇮🇹Italy apaderno Brescia, 🇮🇹

    avpaderno changed the visibility of the branch 3466885-typo-in-docblock to hidden.

  • Status changed to Postponed 6 months ago
  • 🇮🇹Italy apaderno Brescia, 🇮🇹

    Actually, there are more sentences that need to be changed.

    Drupal 7's hook_menu() is now Routing system in Drupal 8.

    Drupal 8's routing system is based on Symfony's routing system.

    There is no need to use two different sentences.

    A route is an entry Drupal 8's router table which contains a path attached to it.

    If it contains a path, the path is attached to it.

    I am not sure that A route is an entry [in] the Drupal 8's router table which contains a path. makes clear what a route is. I would use a different sentence. I am sure the Drupal documentation describes differently a route.

    When a path is requested, Drupal matches the request to a route and if route is match the content is returned else 404 is returned.

    That sentence seem to say something obvious. If then the focus is the differences between Drupal 7 and Drupal 8, that sentence should be removed, since that is not a difference between Drupal 7 and Drupal 8.
    Drupal 7's hook_menu() is now Routing system in Drupal 8. should probably be removed. The rest of the documentation comment should focus on describing what routes are on Drupal 8+.

    The association of a path with a controller, coupled with parameter upcasting and access checking is now handled in the routing system.

    Since Drupal 7 does not have controllers, that sentence cannot say that the association of a path with a controller is now handled in the routing system.

    Drupal loads the routing file that is of the form module_name.routing.yml that it will use to define how Drupal will behave when a specific path is encountered.

    The only new information given in that sentence is that routes are defined in .routing.yml files.
    I do not feel that that is of the form module.routing.yml is a way to say whose filename is <module_name>.routing.yml, where <module_name> is the module machine name.

    If you want to expose content or functionality on your own URIs on a site, routing file is an important part of your module. This can help provide functionality at specific URIs of a website or just modify or augment existing functionality.

    These sentences are not giving new information. The previous sentence already made clear that a .routing.yml file is necessary to define new routes.
    The new information is eventually that a routing file is an important part of a module, but that is not always true: There are module that do not define new routes.
    A routing file is important for a module that defines new routes, but since it was already stated that routes are defined in routing files, there is no need to say they are important for a module.

Production build 0.71.5 2024