The DependencyInjection component lacks usage documentation for implementors.

For starters, I've added documentation for service scopes and synthetic services, which I had to search the net for, and only by coincidence, I thankfully found some pretty essential answers in a forum thread.

Extracted fromhttps://groups.google.com/forum/#!msg/symfony-devs/Uq6dC09O8cg/G6aOeGVaQ-IJ

It's not exactly clear what the best place for these docs inside of Symfony is, so I'm putting this up for initial review and discussion.

In general, my stance is that code documentation should be split into the following areas, which each have their own audience and thus require different content and details:

1. Inline comments: Clarify the technical reasons forwhy something is done exactly in the way it is done. Do not statewhat is being done, unless the code is complex or if it is not obvious.

   Audience: Developers who may touch the code in the future in order tochange it. If they cannot figure out why code was written in the way it was, they will introduce regressions. Tests cannot protect against that.

2. Function-level phpDoc: State exactlywhat the method is doing, and what it doesnot. Clarifywhen the function should be used, and under which circumstances it is invalid to use it. Clarify which parameters exist, if necessary their syntax/format, and most importantly, clarify what their purpose and effect is.

   Audience: Implementors/users who already know (or [mistakenly] believe) that they want or need to use a function.
   Exception: If a method is defined by an interface, the method's phpDoc should live on the interface, instead of the implementation. The implementation should not duplicate the interface documentation.

3. Class-level phpDoc: Explain what the purpose of the class is (and what isnot its purpose), who or what is responsible for instantiating it, how the class and its methods are typically supposed to be used, and how its functionality is involved in the overall big picture.

   Audience: Implementors/users who are trying to make sense of the architectural design and evaluating how to properly implement the component into their own, custom application.

4. Component-level Readme: Provide a high-level introduction to describe the component's purpose, features, and functionality, including simple/common examples. Users seeking for advanced implementation and usage instructions expect to find details in phpDoc, which shouldn't be contained in the Readme, since that has a too high chance of becoming out of date.

   Audience: First-time evaluators of a component, who intend to use it but don't have the slightest idea on how yet. The file is read only once by a single person.

5. Online manual: Explain a component's purpose and features with typical use-case scenarios, focusing on how-tos, tutorials, and examples. Focus on content like help and examples, which cannot or should not be part of the source code.

   Audience: Raw/first-time evaluators of a component, who either do not know yet that they want to use it, or who already attempted to use it, but ran into use-case/scenario-specific problems/questions.

Due to this, my proposal is to add this documentation to theDefinition class, which is essentially the (second) place where I expected to find it, after starting my dive inContainerBuilder. (Due to that, I first considered to add it there, but AFAICS, that class needs an entirely different explanation and amount of documentation to clarify its differentiation fromContainer and relation to involved interfaces and classes likeDefinition.)

Lastly, I'm perfectly aware that the above list of documentation areas goes way beyond this issue, but alas, one always needs to start somewhere ;)

What do you think?