[DependencyInjection] Implementation/usage docs

[sun]

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 from https://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 for why something is done exactly in the way it is done. Do not state what 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 to change 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 exactly what the method is doing, and what it does not. Clarify when 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 is not 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 the Definition class, which is essentially the (second) place where I expected to find it, after starting my dive in ContainerBuilder. (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 from Container and relation to involved interfaces and classes like Definition.)

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?

[stof]

The documentation should be done in the symfony-docs repo instead

[fabpot]

I agree with @stof, the right way would be to add documentation to the DIC component documentation (https://github.com/symfony/symfony-docs/tree/master/components/dependency_injection)

[fabpot]

I've just created an issue on the symfony docs repo.

[sun]

Sorry for replying late; got hit by a flu the past days.

Hm. If I get the contents of symfony-docs right, then you essentially want to add this information to point 5) Online manual.

Frankly though, that's not really where I'd expect technical documentation. As I tried to clarify with the distillation of documentation areas - as a developer, I'd consult the online handbook when searching for conceptual/use-case-specific answers (i.e., tutorials/howtos) -- but not really when I'm trying to make sense of the available properties and methods of a certain class and their meaning.

I also think that a separate and detached online documentation is not able to fully document all methods and possible arguments, as well as their technical relationship and effect with regard to the class' operation. Detached docs like that additionally have the common problem of getting outdated too easily, since the code will be touched and changed over time, and the docs are simply out of sight and not on the radar.

In general, working with Symfony components and their classes could be vastly easier for newcomers if they were better documented. As of now, most classes and methods and their usage is pretty hard to decipher, since they barely describe the Whats and Whys on a technical level, which means that it takes a lot of time to understand the architectural concepts as well as the intended usage of particular resources.

Some resources at least try to document some further technical details, but most often that's not really sufficient to make sense of the author's intentions. Just to provide one of many examples:

    /**
     * Sets the scope of the service
     *
     * @param string $scope Whether the service must be shared or not
...
     */
    public function setScope($scope)

Now, I'm relatively sure that one could write an entire handbook/manual page about use-cases and tutorials/howtos for Scopes (and only Scopes) and their intended usage, as well as the not intended/improper usage... (and the same for every other sub-topic that exists for Definitions)

However, as a developer who's diving into the code in order to implement it correctly, I actually expect architectural as well as technical documentation and reasoning within the code itself, since that is what I'm looking at and what I actually want to find out.

Of course, I need to amend that I'm coming from a Drupal perspective, where we have pretty sophisticated documentation guidelines (of which parts basically translate into the list of docs areas in the OP), and I perfectly know and understand that writing and maintaining excellent code documentation requires work. However, I also want to amend that the topic of Symfony's documentation quality came up a couple of times during our rewrite + implementation phase already, and AFAIK, various people in the Drupal community definitely expressed interest already to improve it. (But alas, everyone has been very busy thus far with figuring out how to properly implement Symfony components without these docs, which is a bit ironic ;))

Hence, an underlying goal here was to reach out and find out how we could improve that situation. :)