Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Already on GitHub? Sign in to your account

[2.2] Symfony\Component\Serializer\Encoder\JsonDecode misses documentation for the "format" and "context" parameters #7492

Closed
felicitus opened this Issue Mar 27, 2013 · 6 comments

Comments

Projects
None yet
2 participants
Contributor

felicitus commented Mar 27, 2013

The documentation for Symfony\Component\Serializer\Encoder\JsonDecode::decode misses documentation for the "format" and "context" parameters.

It seems that "format" isn't used at all, and it is then questionable why the "format" parameter is required for DecoderInterface::decode if it isn't required for implementations. "format" also isn't used within XmlEncoder, which also implements DecoderInterface.

Member

stof commented Mar 27, 2013

A decoder can support several formats, in which case knowing the format when decoding can be needed.
The JsonDecode class does not use it because it only supports the json format and so does not need to switch between different logic.

Contributor

felicitus commented Mar 27, 2013

I'm currently working on a patch for the lack of documentation.

Is it correct to assume that if a DecoderInterface gets passed an unknown $format that the method should throw an error if the format isn't supported?

Member

stof commented Mar 27, 2013

@felicitus A decoder should never receive an unsupported format as the Serializer always calls supportsDecoding($format) first to find the right decoder.

Contributor

felicitus commented Mar 27, 2013

This is true if the Serializer/Deserializer is used. However, when I want to use the class standalone (which I'm doing), there's no way to know which format to pass if the documentation stays as this.

Member

stof commented Mar 27, 2013

Well, when using it standalone, you can still use the supportsDecoding method to be sure that it supports the format

Contributor

felicitus commented Mar 28, 2013

No, how would I know what's a supported format? Is it the commonly used file extension in lower case? What if I pass XML or JSON (both capitalized) as $format? Both decoders would fail in that case, even without letting me know what's wrong. supportsDecoding would simply return false for XML or JSON, and the documentation doesn't tell me about that. Without reading the code itself, nobody would know why it doesn't work. As every person who implements DecoderInterface is free to use any string as a format, it's his obligation to document what value he has chosen for $format.

I see only benefits in saying that people who implement DecoderInterface should document which values for $format are supported, in supportDecoding, supportEncoding, encode and decode.

@fabpot fabpot closed this in 8e8e377 Apr 21, 2013

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment