Clarity, grammer, and style changes to serialization docs #539
Conversation
I made some changes to the serialization documentation for clarity, grammar, and style. There were also a few typos that I corrected.
|
|
||
| ## Using Different Serialization Groups per Operation |
There was a problem hiding this comment.
This case is intended (title case)
|
Thank you, this kind of changes improve the quality of the documentation and are much appreciated! I reverted some changes for consistency with other documentation entries:
It would be awesome if you can proof-read other documents! |
|
@dunglas thanks! I appreciate being able to help with the project, and will continue to do so as time allows. |
| @@ -8,12 +8,12 @@ The main serialization process has two stages: | |||
|
|
|||
|  | |||
|
|
|||
| > As you can see in the picture above, an array is used as a man in the middle. This way, Encoders will only deal with turning specific formats into arrays and vice versa. The same way, Normalizers will deal with turning specific objects into arrays and vice versa. | |||
| > As you can see in the picture above, an array is used as a man-in-the-middle. This way, Encoders will only deal with turning specific formats into arrays and vice versa. The same way, Normalizers will deal with turning specific objects into arrays and vice versa. | |||
There was a problem hiding this comment.
MITM might be understood as an attack lol... Maybe we could say "an intermediary".
There was a problem hiding this comment.
@teohhanhui I agree, although I didn't change that, because I thought it was a direct quote from the Symfony Docs. Looking at the docs, now I see they have updated the language over there.
| -- [The Symfony documentation](https://symfony.com/doc/current/components/serializer.html) | ||
|
|
||
| Unlike Symfony itself, API Platform leverages custom normalizers, its router and the [data provider](data-providers.md) system to do an advanced transformation. Metadata are added to the generated document including links, type information, pagination data or available filters. | ||
|
|
||
| The API Platform Serializer is extendable, you can register custom normalizers and encoders to support other formats. You can also decorate existing normalizers to customize their behaviors. | ||
| The API Platform Serializer is extendable. You can register custom normalizers and encoders in order to support other formats. You can also decorate existing normalizers to customize their behaviors. |
There was a problem hiding this comment.
In the context of PHP, "extendable" might give the wrong idea of the class being able to be extended, so perhaps we could use the synonym "extensible".
There was a problem hiding this comment.
@teohhanhui Agreed.
I made some changes to the serialization documentation for clarity, grammar, and style. There were also a few typos that I corrected.
If you think this is a worthwhile PR, I would be happy to provide suggestions for some of the other pages in the documentation as well.