Skip to content

[RFC] Updating the documentation of the Yaml component #6543

New issue

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

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Closed
javiereguiluz opened this issue May 8, 2016 · 3 comments
Closed

[RFC] Updating the documentation of the Yaml component #6543

javiereguiluz opened this issue May 8, 2016 · 3 comments
Labels
Yaml

Comments

@javiereguiluz
Copy link
Member

In http://symfony.com/doc/current/components/yaml/introduction.html we explain how to parse and dump using two different methods: Parser/Dump classes and static methods of Yaml class.

I don't like when we have several ways of doing the same thing ... and I like it less when we don't explain their differences or tell the user when to use each alternative.

So I propose the following:

  • Use the static methods to show the basic usage.
  • Explain the object oriented API later in a new section of that article.
  • Add some info about when to use each alternative.
@HeahDude
Copy link
Contributor

HeahDude commented May 8, 2016

👍 Any thought on #6524? If you want to suggest a clear roadmap here we could close it.

@xabbuh xabbuh added the Yaml label May 9, 2016
@xabbuh
Copy link
Member

xabbuh commented May 22, 2016

Oh, I completely missed this issue when creating #6598. So the first task is checked now anyway.

However, I don't think we really need to explain the internal API. I cannot think of a use case that justifies using the Parser or Dumper class directly that is so common that we should include it in the documentation. Developers who are in the need of using the classes directly will still be able to figure out how to do that themselves.

@javiereguiluz
Copy link
Member Author

I'm closing this because of being partially fixed by #6524 and being partially duplicated by #6226.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
Yaml
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
3 participants
@javiereguiluz @xabbuh @HeahDude