Problem/Motivation

Unlike many other pages of core documentation, the Block API documentation doesn't contain a worked example.

Compare:

* https://api.drupal.org/api/drupal/core%21lib%21Drupal%21Core%21Menu%21me...
* https://api.drupal.org/api/drupal/core%21lib%21Drupal%21Core%21Routing%2...
* https://api.drupal.org/api/drupal/core%21core.api.php/group/form_api/8.2.x
* https://api.drupal.org/api/drupal/core%21modules%21block%21block.api.php...

While the Block API documentation links off to examples elsewhere in a contrib module, this is probably not great practice (and definitely not consistent with the other API docs.)

Proposed resolution

Add an example to block.api.php
Add sections.
Do not remove references to \Drupal\Core\Block\Annotation\Block. let's do that in a separate issue

Remaining tasks

Review
Commit

User interface changes

None.

API changes

None.

Data model changes

None.

CommentFileSizeAuthor
#28 2798531-nr-bot.txt663 bytesneeds-review-queue-bot
#18 interdiff_17-18.txt294 bytesranjith_kumar_k_u
#18 2798531-18.patch2.14 KBranjith_kumar_k_u
#17 add_example_to_core-2798531-17.patch2.04 KBAnkit.Gupta
#4 add_example_to_core-2798531-4.patch2.03 KBjp.stacey
#2 add_example_to_core-2798531-2.patch2.29 KBjp.stacey

Issue fork drupal-2798531

Command icon Show commands

Start within a Git clone of the project using the version control instructions.

Or, if you do not have SSH keys set up on git.drupalcode.org:

About issue forks

Comments

jp.stacey created an issue. See original summary.

jp.stacey’s picture

jp.stacey commented
Status: Active » Needs review
StatusFileSize
new add_example_to_core-2798531-2.patch2.29 KB

Patch attached for discussion.

jp.stacey’s picture

jp.stacey commented
Component: block.module » documentation
Issue tags: -documentation bug +example, +block
jp.stacey’s picture

jp.stacey commented
StatusFileSize
new add_example_to_core-2798531-4.patch2.03 KB

Patch from #2 re-rolled as @kiwimind pointed out the embedded docblocks: no other worked examples have them, so I'm going to remove them to make the example simpler and avoid any issues with formatting docblocks within docblocks for api.drupal.org.

Version: 8.3.x-dev » 8.4.x-dev

Drupal 8.3.0-alpha1 will be released the week of January 30, 2017, which means new developments and disruptive changes should now be targeted against the 8.4.x-dev branch. For more information see the Drupal 8 minor version schedule and the Allowed changes during the Drupal 8 release cycle.

lomo’s picture

lomo commented
Version: 8.4.x-dev » 8.3.x-dev
Category: Bug report » Task
Status: Needs review » Reviewed & tested by the community

I don't think this should be filed as a "bug report", so I've changed it to a "Task". (Maybe I'm wrong about what qualifies as a "bug", but I personally wouldn't categorize "needed documentation improvements" as a "bug".)

That said, I also think this has been waiting for commit for far too long. The improvements from @jp.stacey look good to me. (I even set up a local Drupal 8 API server pointing to my local checkout of Drupal 8.x-4.x to verify that the documentation changes parse nicely and compared before/after versions of the affected file in a full-file diff-viewer to see everything in context.)

I think this can be set to RTBC and committed. Reviewing the rules for minor release changes, I think this should be allowable and should not need to wait for 8.4.x, therefore, I've also changed the version tag back to its previous value of 8.3.x-dev. This only affects documentation and basically only adds a bit more to the API docs, so it should be trivial enough not to require waiting for the next major release of Drupal 8. If I'm wrong about that, please correct me. ;-)

gábor hojtsy’s picture

gábor hojtsy
he/him
Primary language Hungarian
Location Hungary
commented
Status: Reviewed & tested by the community » Needs review

I have little familiarity with the example docs structures. So I went to check if this applies patterns used elsewhere:

$ git grep sec_overview
core/core.api.php: * @section sec_overview Overview of web services
core/core.api.php: * @section sec_overview Overview and terminology
core/core.api.php: * @section sec_overview Overview of container, injection, and services
core/core.api.php: * @section sec_overview Overview
core/core.api.php: * @section sec_overview Overview and terminology
core/core.api.php: * @section sec_overview Overview of Ajax
core/lib/Drupal/Core/Menu/menu.api.php: * @section sec_overview Overview and terminology
core/lib/Drupal/Core/Routing/routing.api.php: * @section sec_overview Overview and terminology
$ git grep sec_requirements
[no results]
$ git grep sec_extending
[no results]
$ git grep sec_further_information
[no results]
$ git grep examplemodule
[no results]

I was assuming the example module would at least be appearing in other examples as well, but that does not seem to be the case. Is this docs section based off of some pattern or is it introducing a new one? How are code examples in other section represented?

Version: 8.3.x-dev » 8.4.x-dev

Drupal 8.3.6 was released on August 2, 2017 and is the final full bugfix release for the Drupal 8.3.x series. Drupal 8.3.x will not receive any further development aside from critical and security fixes. Sites should prepare to update to 8.4.0 on October 4, 2017. (Drupal 8.4.0-alpha1 is available for testing.)

Bug reports should be targeted against the 8.4.x-dev branch from now on, and new development or disruptive changes should be targeted against the 8.5.x-dev branch. For more information see the Drupal 8 minor version schedule and the Allowed changes during the Drupal 8 release cycle.

Version: 8.4.x-dev » 8.5.x-dev

Drupal 8.4.4 was released on January 3, 2018 and is the final full bugfix release for the Drupal 8.4.x series. Drupal 8.4.x will not receive any further development aside from critical and security fixes. Sites should prepare to update to 8.5.0 on March 7, 2018. (Drupal 8.5.0-alpha1 is available for testing.)

Bug reports should be targeted against the 8.5.x-dev branch from now on, and new development or disruptive changes should be targeted against the 8.6.x-dev branch. For more information see the Drupal 8 minor version schedule and the Allowed changes during the Drupal 8 release cycle.

Version: 8.5.x-dev » 8.6.x-dev

Drupal 8.5.6 was released on August 1, 2018 and is the final bugfix release for the Drupal 8.5.x series. Drupal 8.5.x will not receive any further development aside from security fixes. Sites should prepare to update to 8.6.0 on September 5, 2018. (Drupal 8.6.0-rc1 is available for testing.)

Bug reports should be targeted against the 8.6.x-dev branch from now on, and new development or disruptive changes should be targeted against the 8.7.x-dev branch. For more information see the Drupal 8 minor version schedule and the Allowed changes during the Drupal 8 release cycle.

Version: 8.6.x-dev » 8.8.x-dev

Drupal 8.6.x will not receive any further development aside from security fixes. Bug reports should be targeted against the 8.8.x-dev branch from now on, and new development or disruptive changes should be targeted against the 8.9.x-dev branch. For more information see the Drupal 8 and 9 minor version schedule and the Allowed changes during the Drupal 8 and 9 release cycles.

Version: 8.8.x-dev » 8.9.x-dev

Drupal 8.8.7 was released on June 3, 2020 and is the final full bugfix release for the Drupal 8.8.x series. Drupal 8.8.x will not receive any further development aside from security fixes. Sites should prepare to update to Drupal 8.9.0 or Drupal 9.0.0 for ongoing support.

Bug reports should be targeted against the 8.9.x-dev branch from now on, and new development or disruptive changes should be targeted against the 9.1.x-dev branch. For more information see the Drupal 8 and 9 minor version schedule and the Allowed changes during the Drupal 8 and 9 release cycles.

Version: 8.9.x-dev » 9.2.x-dev

Drupal 8 is end-of-life as of November 17, 2021. There will not be further changes made to Drupal 8. Bugfixes are now made to the 9.3.x and higher branches only. For more information see the Drupal core minor version schedule and the Allowed changes during the Drupal core release cycle.

Version: 9.2.x-dev » 9.3.x-dev

Version: 9.3.x-dev » 9.4.x-dev

Drupal 9.3.15 was released on June 1st, 2022 and is the final full bugfix release for the Drupal 9.3.x series. Drupal 9.3.x will not receive any further development aside from security fixes. Drupal 9 bug reports should be targeted for the 9.4.x-dev branch from now on, and new development or disruptive changes should be targeted for the 9.5.x-dev branch. For more information see the Drupal core minor version schedule and the Allowed changes during the Drupal core release cycle.

amber himes matz’s picture

amber himes matz
she/her
Primary language English
Location Portland, OR USA
commented
Status: Needs review » Needs work
Issue tags: +Needs reroll

Let's get this rerolled and then take another look at it.

Ankit.Gupta’s picture

Ankit.Gupta commented
Status: Needs work » Needs review
Issue tags: -Needs reroll
StatusFileSize
new add_example_to_core-2798531-17.patch2.04 KB

Reroll the patch #4 with Drupal 9.4.x

ranjith_kumar_k_u’s picture

ranjith_kumar_k_u commented
StatusFileSize
new 2798531-18.patch2.14 KB
new interdiff_17-18.txt294 bytes

Fixed Cspell issue.

Version: 9.4.x-dev » 9.5.x-dev

Drupal 9.4.9 was released on December 7, 2022 and is the final full bugfix release for the Drupal 9.4.x series. Drupal 9.4.x will not receive any further development aside from security fixes. Drupal 9 bug reports should be targeted for the 9.5.x-dev branch from now on, and new development or disruptive changes should be targeted for the 10.1.x-dev branch. For more information see the Drupal core minor version schedule and the Allowed changes during the Drupal core release cycle.

smustgrave’s picture

smustgrave commented
Status: Needs review » Needs work
Issue tags: +Needs Review Queue Initiative

To avoid an additional cspell word to keep track I think we should replace examplemodule with just example or module.

Version: 9.5.x-dev » 11.x-dev

Drupal core is moving towards using a “main” branch. As an interim step, a new 11.x branch has been opened, as Drupal.org infrastructure cannot currently fully support a branch named main. New developments and disruptive changes should now be targeted for the 11.x branch. For more information, see the Drupal core minor version schedule and the Allowed changes during the Drupal core release cycle.

quietone made their first commit to this issue’s fork.

quietone opened merge request !8593

quietone’s picture

quietone commented
Title: Add example to core Block API documentation » Add example and sections to core Block API documentation
Issue summary: View changes
Status: Needs work » Needs review
quietone’s picture

quietone commented
smustgrave’s picture

smustgrave commented
Status: Needs review » Reviewed & tested by the community
Related issues: +#3458803: Remove reference to \Drupal\Core\Block\Annotation\Block (possibly more?)

Example seems correct to me.

I opened #3458803: Remove reference to \Drupal\Core\Block\Annotation\Block (possibly more?) for the annotation removal. I left an open question on that ticket about scope range.

quietone’s picture

quietone commented
Title: Add example and sections to core Block API documentation » Add example and sections to Block API documentation
needs-review-queue-bot’s picture

needs-review-queue-bot commented
Status: Reviewed & tested by the community » Needs work
StatusFileSize
new 2798531-nr-bot.txt663 bytes

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

This does not mean that the patch necessarily needs to be re-rolled or the MR rebased. Read the Issue Summary, the issue tags and the latest discussion here to determine what needs to be done.

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

quietone’s picture

quietone commented
Status: Needs work » Needs review
Issue tags: +no-needs-review-bot
smustgrave’s picture

smustgrave commented
Status: Needs review » Reviewed & tested by the community

Restoring previous status before the bot.

longwave made their first commit to this issue’s fork.

nod_ closed merge request !8593

  • nod_ committed c9db648a on 11.x 
    Issue #2798531 by quietone, jp.stacey, ranjith_kumar_k_u, Ankit.Gupta,...
nod_’s picture

nod_
Primary language French
Location Lille
commented
Status: Reviewed & tested by the community » Fixed

Committed c9db648 and pushed to 11.x. Thanks!

Status: Fixed » Closed (fixed)

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