The description given for FactoryInterface::createInstance() and MapperInterface::getInstance() are too similar.

Creates a pre-configured instance of a plugin.

Gets a preconfigured instance of a plugin.

These two sentences are almost identical. They seem to mean the same thing. There are two different methods which surely do different things, so the description should be different.

CommentFileSizeAuthor
#20 2960381-20.patch1.15 KBroshni27

Comments

joachim created an issue. See original summary.

msankhala’s picture

msankhala commented

@joachim Yes it seems identical, In your opinion what should be the better explanation?

I think createInstance() delegate the creation of plugin instance to the Factory while getInstance() gets the plugin instance by passing configuration to Factory which creates the plugin instance. Correct?

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

Drupal 8.6.0-alpha1 will be released the week of July 16, 2018, which means new developments and disruptive changes should now 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.7.x-dev » 8.8.x-dev

Drupal 8.7.0-alpha1 will be released the week of March 11, 2019, which means new developments and disruptive changes should now be targeted against the 8.8.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.8.x-dev » 8.9.x-dev

Drupal 8.8.0-alpha1 will be released the week of October 14th, 2019, which means new developments and disruptive changes should now be targeted against the 8.9.x-dev branch. (Any changes to 8.9.x will also be committed to 9.0.x in preparation for Drupal 9’s release, but some changes like significant feature additions will be deferred to 9.1.x.). 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.1.x-dev

Drupal 8.9.0-beta1 was released on March 20, 2020. 8.9.x is the final, long-term support (LTS) minor release of Drupal 8, which means new developments and disruptive changes should now 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: 9.1.x-dev » 9.2.x-dev

Drupal 9.1.0-alpha1 will be released the week of October 19, 2020, which means new developments and disruptive changes should now be targeted for the 9.2.x-dev branch. For more information see the Drupal 9 minor version schedule and the Allowed changes during the Drupal 9 release cycle.

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

Drupal 9.2.0-alpha1 will be released the week of May 3, 2021, which means new developments and disruptive changes should now be targeted for the 9.3.x-dev branch. For more information see the Drupal core minor version schedule and the Allowed changes during the Drupal core release cycle.

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

Drupal 9.3.0-rc1 was released on November 26, 2021, which means new developments and disruptive changes should now be targeted for the 9.4.x-dev branch. For more information see the Drupal core minor version schedule and the Allowed changes during the Drupal core release cycle.

larowlan’s picture

larowlan
Location 🇦🇺🏝.au GMT+10
commented
Priority: Normal » Minor
Issue tags: +Documentation, +Bug Smash Initiative
larowlan’s picture

larowlan
Location 🇦🇺🏝.au GMT+10
commented
Issue tags: +Novice
joachim’s picture

joachim commented

To summarise:

- createInstance() instantiates a plugin for a specific ID, with optionally, options. I don't think 'preconfigured' applies here.
- getInstance() allows you to pass just some options, and it figured out a suitable plugin ID

getInstance() is *weird*. Its docs and signature make it look like you pass in some plugin options, and you get a plugin that satisfied those which, I dunno, just happened to be lying around already. But in most cases,

avpaderno’s picture

avpaderno
he/him
Primary language Italian
Location Brescia, 🇮🇹 🇪🇺
commented

The difference between those methods is exactly what the documentation says: A method creates a plugin instance, while the other gets an existing plugin instance (if it exists) or creates it (if it doesn't exist).
The short documentation line is required to be a single line; it's quite hard to make the difference clearer with that restriction. Eventually, it's the longer description that should give more details.

avpaderno’s picture

avpaderno
he/him
Primary language Italian
Location Brescia, 🇮🇹 🇪🇺
commented
Title: DefaultPluginManager docs for createInstance() and getInstance() are almost identical » The description for FactoryInterface::createInstance() and MapperInterface::getInstance() are too similar
Issue summary: View changes

Those methods are defined in two different interfaces extended by PluginManagerInterface, which is interface implemented by classes like DefaultPluginManager.

avpaderno’s picture

avpaderno
he/him
Primary language Italian
Location Brescia, 🇮🇹 🇪🇺
commented
Title: The description for FactoryInterface::createInstance() and MapperInterface::getInstance() are too similar » Add explanation paraghraphs to the documentation for FactoryInterface::createInstance() and MapperInterface::getInstance()
Category: Bug report » Task
Priority: Minor » Normal

Also, it's true that both the methods return pre-configured instances of plugins, but those are the only plugin instances. There is no need to say pre-configured.

joachim’s picture

joachim commented
Title: Add explanation paraghraphs to the documentation for FactoryInterface::createInstance() and MapperInterface::getInstance() » Docs FactoryInterface::createInstance() and MapperInterface::getInstance() are too similar and need more detail

The first lines should be changed. We really should be able to come up with something to differentiate them.

How about:

- Creates an instance of a plugin.

- Gets an instance of a plugin which satisfies given options, or creates one.

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

Drupal 9.4.0-alpha1 was released on May 6, 2022, which means new developments and disruptive changes should now 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.

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

Drupal 9.5.0-beta2 and Drupal 10.0.0-beta2 were released on September 29, 2022, which means new developments and disruptive changes should now 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.

Version: 10.1.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, which currently accepts only minor-version allowed changes. For more information, see the Drupal core minor version schedule and the Allowed changes during the Drupal core release cycle.

roshni27’s picture

roshni27 commented
Status: Active » Needs review
StatusFileSize
new 2960381-20.patch1.15 KB

I have made changes according to #15 and #16.

smustgrave’s picture

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

Seems suggestion in #15 has been implemented.

@roshni27 thank you for working on it. Looking at your post history believe you can work on non-novice issue now. Novice issues are meant to be reserved for new users. Thanks!

roshni27’s picture

roshni27 commented

Thank you for your feedback! I appreciate your guidance on the issue categorization. I'll make sure to focus on non-novice issues going forward.

  • xjm committed 02f6f6c6 on 11.x 
    Issue #2960381 by roshni27, joachim, apaderno, smustgrave: Docs for...

  • xjm committed b726c12a on 10.2.x 
    Issue #2960381 by roshni27, joachim, apaderno, smustgrave: Docs for...

  • xjm committed b375ef98 on 10.1.x 
    Issue #2960381 by roshni27, joachim, apaderno, smustgrave: Docs for...
xjm’s picture

xjm
she/her
Primary language English
commented
Status: Reviewed & tested by the community » Fixed

Nice improvement, thanks!

Crediting @joachim and @apaderno for researching and proposing the improvements, @smustgrave for mentoring, and @roshni27 for the patch.

Committed to 11.x, 10.2.x, and 10.1.x as a patch-eligible documentation improvement. Thanks everyone!

xjm’s picture

xjm
she/her
Primary language English
commented
Version: 11.x-dev » 10.1.x-dev

Status: Fixed » Closed (fixed)

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