ParamConverterInterface one-line description doesn't explain what the class does

I disagree with this meta issue... A well-chosen class name may not need any further one-line documentation that expands on it, and just because the one-line doesn't tell you anything more doesn't necessarily mean it's a bug.

So I'm making this a specific issue for this class, since this doesn't say what type of parameters are converted to what, and definitely it needs more information.

I was going to mark this novice, but since I also have no idea what this interface is for... hopefully someone does!

Oh, I see on this issue that joachim explains what these parameter converters are for:
#2087107: document routing.yml parameter converters

So probably a novice could come up with a good patch for this.

Working on this at Drupal Camp Costa Rica.

Added small long description.

Thanks for the patch -- good start!

So... I think we want to replace the existing first-line docs for this interface with documentation that actually gives us some information -- assuming we can do that in one 80-character line. Maybe, taking what you wrote, it could be:

Defines an interface for converting route parameters to classes.

[note that you misspelled classsed in your patch]

Then in a second paragraph, we can expand that information to explain what "parameters" mean in this case, and how/why they are converted to classes. I still am not sure what that means actually... and maybe this isn't such a great Novice project? Well, maybe you know more than I do, or maybe you can get help from someone in IRC with understanding it?

I was actually sitting next to Rick as he wrote this patch at an impromptu DrupalCamp CR new contributors sprint. :-) I like Jen's suggestion for improving the short description, and then just fixing up the spelling in the long description. (Explaining what a route parameter is is out of scope for this docblock, IMO.)

Rick, can you update the patch?

Where would you put it?

In some d.o-based documentation on the routing system. Why should we spread routing system documentation all over the code base? How would you know which of our 1000+ classes to look at for a detailed explanation of implementation details of 3 different systems interacting?

Besides, "implementation details" do not belong on an interface anyway. :-)

Added issue summary template.

Rather amazed to find that #4 still applies.

Changed the docblock to look like this:

/**
 * Interface for parameter converters.
 *
 * Classes implementing this interface are responsible for converting a path
 * parameter to the object it represents.
 *
 * Here is an example path:
 * @code
 * /admin/structure/block/manage/{block}
 * @endcode
 * In this case, 'block' would be the path parameter which should be turned into
 * the block in question for administration.
 *
 * @see menu
 */

Also some action-verb changes to the method docblocks.

There isn't a routing topic on api.drupal.org, but there is @menu which is 'menu and routing,' which punts to Symfony documentation wrt routing.

Not sure why SimpleTestBrowserTest is unhappy with my docblock changes, but there you go.

1. +++ b/core/lib/Drupal/Core/ParamConverter/ParamConverterInterface.php
   @@ -11,11 +11,23 @@
   + * In this case, 'block' would be the path parameter which should be turned into
   + * the block in question for administration.
   

   "block object". Or ideally, specify the class name of the object. Returning a stdClass would be an error.

2. +++ b/core/lib/Drupal/Core/ParamConverter/ParamConverterInterface.php
   @@ -11,11 +11,23 @@
   +   * Convert path variables to their corresponding objects.
   

   ConvertS

3. +++ b/core/lib/Drupal/Core/ParamConverter/ParamConverterInterface.php
   @@ -32,7 +44,7 @@
   +   * Determine if the converter applies to a specific route and variable.
   

   DetermineS

Thanks.

For #1, it's an interface so saying {block} always returns a specific class isn't the way to go. Also, I just learned a bunch more about ParamConverters, that they're services, and that they're managed by a central service. So woot. :-)

#2 and #3: Nice.

/**
 * Interface for parameter converters.
 *
 * Classes implementing this interface are responsible for converting a path
 * parameter to the object it represents.
 *
 * Here is an example path:
 * @code
 * /admin/structure/block/manage/{block}
 * @endcode
 * In this case, '{block}' would be the path parameter which should be turned
 * into a block object representing the block in question.
 *
 * ParamConverters are defined as services tagged with 'paramconverter', and are
 * managed by the 'paramconverter_manager' service.
 *
 * @see menu
 * @see \Drupal\Core\ParamConverter\ParamConverterManagerInterface
 * @see \Drupal\Core\ParamConverter\EntityConverter
 */

Looks good to me! One minor nitpick:

+++ b/core/lib/Drupal/Core/ParamConverter/ParamConverterInterface.php
@@ -11,11 +11,28 @@
+ * Here is an example path:
+ * @code
+ * /admin/structure/block/manage/{block}
+ * @endcode
+ * In this case, '{block}' would be the path parameter which should be turned

This should not be in a @code block, I think?

Done.

OK let's do. Thanks!

This is so much better than before. Well done!

This issue only changes documentation, so per https://www.drupal.org/core/beta-changes, this can be completed any time during the Drupal 8 beta phase. Committed and pushed to 8.0.x, thanks!