getParameters() vs. getRawParameters() on RouteMatch should not be documented the same

Good question. I personally have no idea, but I agree that some documentation would help... The parameters and raw parameters are passed into the constructor though...

So here's one file that uses this class...
https://api.drupal.org/api/drupal/core!lib!Drupal!Core!Access!AccessMana...
In the Source listing, you can see that it constructs a RouteManager by 'upcasting' (whatever that means) the parameters, and then passing those "upcasted" parameters into the constructor.

So it looks like they are some sort of manipulated parameters, and probably whatever the user of the class defines as "not raw" is what they are... not sure what we should put into the docs... assiging to route system component for clarification.

So yeah to clarify, rawParameters are the parameters which comes directly from the URL. parameters on the other hand are potentially upcasted using
the param conversion system. So for example on /node/{node} getRawParameter('node') returns 123 but getParameter('node') returns the full entity object.

Great, thanks! This should be documented. Given the explanation in comment #2, probably now a Novice task?

Updated RouteMatchInterface.php to include:

RouteMatch::getParameters: Returns the bag of all route parameters (potentially upcasted by the param conversion system).
RouteMatch::getParameter: Returns the value of a named route parameter (potentially upcasted by the param conversion system).
RouteMatch::getRawParameters: Returns the bag of all raw route parameters (those used in the URL).
RouteMatch::getRawParameter: Returns the raw value (the one used in the URL) of a named route parameter.

Thanks! This is a good start.

We have a documentation standard that each doc block must start with one sentence of <= 80 characters. So the docs are too long on these functions. My suggestion would be to say something like these in the first lines:

Returns the processed value of a named route parameter.
Returns the raw value of a named route parameter.
etc.

And then for the processed ones, after a blank line, you can add a longer explanation... I don't think "upcasted" is very clear either, and really converting something like "12345" to a fully-loaded Node object is not really an "upcast" anyway, is it? So since this explanation can be longer than one line, maybe you can explain it in a clearer way than just saying "upcast by the param conversion system". Also, please do not use non-words like "param" -- spell out the full word "parameter".

So... just needs a little revision and editing! Thanks!

I did not get the issue number right before in my patch, sorry.
I have broken long lines, and have explaned "upcast" as a possible node conversion.
By the way, I see there is the GetRouteObject() method, is it much different?

I guess status should be Need Review.

+++ b/core/lib/Drupal/Core/Routing/RouteMatchInterface.php
@@ -39,7 +39,8 @@ public function getRouteName();
+   * (potentially converted to node by the parameter conversion system).

@@ -51,7 +52,8 @@ public function getRouteObject();
+   * (potentially converted to nodes by the parameter conversion system).

I don't think we should explicitly talk about nodes here, maybe we should point to the parameter converting system instead? One congrete example of the difference would be nice. ... getParameter() returns the entity object, getRawParameter() just the ID.

Agreed on #12. Node conversion is just an example, not what we want in generic docuementation.

Also:

   /**
-   * Returns the value of a named route parameter.
+   * Returns the value of a named route parameter
+   * (potentially converted to node by the parameter conversion system).

Please read https://www.drupal.org/node/1354#drupal :

All summaries (first lines of docblocks) must be under 80 characters, start with a capital letter, and end with a period (.). They must provide a brief description of what a function does, what a class does, what a file contains, etc.

In other words: One line. One sentence. Not two lines at the beginning of a doc block. As I tried to say in #7, you need to start with a one-line summary, and put additional documentation in a separate paragraph. I even made some suggestions for the one-line summaries in #7.

Thanks!

OK, trying to patch again following the advices.

That's good! Do you think we need additional explanation added to the non-raw methods, to explain what "processed" means? This could be put in an additional paragraph... let's see. Maybe we could say:

Raw URL parameters are processed by the parameter conversion system, which does operations such as converting entity ID parameters to fully-loaded entities. For example, the path node/12345 would have a raw node ID parameter value of 12345, while the processed parameter value would be the corresponding loaded node object.

Thoughts?

I'm also wondering if the "raw" methods should have the word "raw" inserted in their one-line descriptions as well, and should there be @see lines connecting the raw/processed methods (if there aren't already)?

Hi I am a high school student who is new to drupal. I have tried to add the changes suggested by @jhodgdon and have attached my patch :)

That looks great, thanks! I still wonder if the "raw" methods should have "raw" in their one-line summary descriptions? Oh wait, they already do (probably was changed since the issue was originally filed). That's good. Thanks!

Documentation is not frozen during beta. Committed ed1c7ba and pushed to 8.0.x. Thanks!